Úvod
Komentáře ve skriptování bash a programování obecně pomáhají programu snáze porozumět. Když je program spuštěn, interpret ignoruje komentované řádky. Komentáře však pomáhají s celkovou čitelností programu.
Když se na kód podíváte později, pomůže vám mít popisná a hodnotná vysvětlení toho, co kód dělá. Komentování kódu pro pozdější použití je běžnou praxí a je nezbytnou součástí programování a bash skriptování.
Tento výukový program ukazuje, jak používat komentáře a nejlepší postupy při komentování ve skriptech bash.
Předpoklady
- Systém se systémem Linux.
- Přístup k příkazovému řádku/terminálu.
- Textový editor, jako je Vi/Vim.
Jak komentovat v Bash
Při psaní bash skriptů jakýkoli text za znakem hash (# ) označuje začátek komentáře a jakýkoli text za # ve stejném řádku se neprovede.
Při použití textového editoru nebo IDE jsou komentáře barevně odlišné od zbytku kódu. Je snadné si jich všimnout a vyhledat je v rozšířených kódech.
Jedinou výjimkou je shebang (#! ), který je obvykle na prvním řádku skriptu. Shebang říká operačnímu systému, který interpret má pro kód použít.
Vložené komentáře po shebang mají za následek „Žádný takový soubor nebo adresář "chyba."
Jeden řádek a vložený komentář Bash
Jednořádkové i vložené komentáře ve skriptech bash začínají znakem hash (# ):
# This is a commentDodatečná mezera za znakem není nutná. Pomáhá však s čitelností.
Chcete-li vytvořit skript s komentáři, postupujte podle níže uvedeného příkladu:
1. Otevřete terminál (CTRL +ALT +T ) a vytvořte skript pomocí Vi:
vi comment.sh2. Přidejte následující kód:
# A comment is considered a single line if you do not press Enter. Below is the shebang, indicating the script uses the bash shell.
#!/bin/bash
# This is a single line comment above a command.
echo "Hello world!" # This is an inline comment.
# This is a single line comment below a command.
Skript obsahuje následující řádky:
- Řádek 1 je jednořádkový Bash komentář. Vizuálně se prohlášení rozkládá na dvou řádcích.
- Řádek 2 je shebang. Skript se spouští pomocí interpretu shellu Bash, který se nachází v /bin/bash .
- Řádky 3 a 5 jsou také jednořádkové komentáře před a za příkazem.
- Řádek 4 je jednoduchý příkaz echo s vloženým komentářem.
3. Uložte a zavřete Vi:
:wq4. Změňte oprávnění skriptu na spustitelný:
chmod +x comment.sh5. Nakonec spusťte skript pomocí:
./comment.sh
Komentáře se při provádění skriptu nezobrazují .
Multiline a Block Bash Comment
Chcete-li vytvořit víceřádkové bash komentáře, začněte každý řádek znakem hash (# ):
# This is the first line
# This is the second line
Dalším nekonvenčním způsobem, jak vytvořit víceřádkové blokové komentáře, je použití příkazu bash null (: ) spolu se zápisem heredoc:
: << 'COMMENT'
This is the first line
This is the second line
COMMENT
Bash v zásadě nepodporuje blokové komentáře. Tato metoda funguje jako hack, pokud je blokový komentář pro konkrétní případ nezbytný.
Vyzkoušejte níže uvedený příklad, abyste viděli, jak víceřádkové a blokové komentáře fungují ve skriptech bash:
1. Otevřete terminál (CTRL +ALT +T ) a vytvořte skript shellu pomocí Vi:
vi multiline.sh2. Zkopírujte a vložte následující kód:
: << 'COMMENT'
This is a multiline block comment
using the single quote heredoc
and bash null command.
COMMENT
echo "Hello world!"
# This is a multiline comment
# using the single line notation.
Kód dělá následující:
- Řádek 1 a 5 jsou heredoc oddělovače.
- Řádky 2–4 jsou obsahem komentáře bloku.
- Řádek 6 je
echopříkaz. - Řádky 7–8 jsou víceřádkové komentáře, které fungují jako víceřádkové komentáře.
3. Uložte soubor a zavřete Vi:
:wq4. Změňte oprávnění skriptu na spustitelný soubor:
chmod +x multiline.sh5. Nakonec spusťte skript, abyste viděli výstup:
./multiline.sh
Výstup terminálu zobrazuje pouze výsledek v echo příkaz, zatímco komentované řádky se nezobrazují.
Osvědčené postupy a tipy pro komentáře Bash
Ačkoli neexistují žádná specifická pravidla pro komentování v bash, určité postupy jsou užitečné při používání komentářů. Tyto postupy a tipy vám pomohou vytěžit maximum z komentování v bash.
1. Zahrnout záhlaví souboru
Všechny skripty, které nejsou na první pohled tak patrné, by měly obsahovat hlavičku souboru. Záhlaví slouží několika účelům:
- Na první pohled vysvětluje, co kód dělá.
- Označuje autorství.
- Vysvětluje oznámení o licenci a poskytuje prohlášení o povolení pro kód chráněný autorským právem.
K vysvětlení těchto bodů použijte komentáře na začátku kódu. Pokud je kód součástí projektu, uveďte také název projektu.
2. Vyhněte se nekonvenčním blokovým komentářům
Ačkoli jsou blokové komentáře v bash skriptech možné, je špatným zvykem je používat. Kód není tak snadno rozpoznatelný jako běžný komentář, protože textové editory je nevykreslují jako komentáře. Kromě toho je vyhledávání mnohem jednodušší, když existuje jednotná syntaxe komentářů.
3. Vyhněte se dlouhým a zbytečným komentářům
Udržujte komentáře co nejkratší a k věci. Upovídanost je zbytečná a kód je hůře čitelný.
Stejně tak komentujte pouze kód, který je těžko uchopitelný. Komentář k jednoduchému echo příkaz je zbytečný, zatímco kód, který používá komplexní příkaz regulárního výrazu, vyžaduje rychlou indikaci toho, co dělá.
4. Komentáře a funkce
Všechny bash funkce těží z komentářů, které vysvětlují účel, očekávané vstupy a výstupy. Výjimkou jsou krátké části kódu, které jsou zjevné.
Pro každou funkci uveďte následující:
- Stručný popis operace.
- Seznam globálních nebo upravených proměnných.
- Očekávané vstupní argumenty.
- Co proces odesílá do terminálu.
- Očekávané návratové hodnoty.
Níže je uveden příklad funkce, která dokumentuje každý z předchozích bodů:
PREFIX="Hello "
#### FUNCTION BEGIN
# Prints a greeting
# GLOBALS:
# PREFIX
# ARGUMENTS:
# Name as a String to use for greeting
# OUTPUTS:
# Writes String to STDOUT
# RETURN:
# 0 if success, non-zero otherwise.
### FUNCTION END
function () {
echo "${PREFIX}: $1!"
}
Upravte příklad svému případu použití.
5. Označujte konzistentně
Použijte komentáře k označení kódu, který potřebuje vylepšení, implementaci nebo úpravu. Vytvořte konzistentní štítek s komentáři pro jiný úkol, abyste si usnadnili vyhledávání v komentářích.
Například každé vysvětlení funkce začněte a ukončete pomocí # FUNCTION BEGIN nebo přidejte # TODO komentáře pro budoucí úkoly. Podobně se rozhodněte, které štítky se zdají vhodné, a zůstaňte konzistentní v celém kódu.