Come commentare in Bash

Introduzione

I commenti nello scripting bash e nella programmazione in generale aiutano a rendere un programma più facile da capire. Quando un programma viene eseguito, l'interprete ignora le righe commentate. Tuttavia, i commenti aiutano con la leggibilità generale del programma.

Quando si esamina il codice in un secondo momento, è utile avere spiegazioni descrittive e preziose su ciò che fa il codice. Commentare il codice per un uso successivo è una pratica comune ed è una parte essenziale della programmazione e degli script bash.

Questo tutorial mostra come utilizzare i commenti e le migliori pratiche per la creazione di commenti negli script bash.

Prerequisiti

• Un sistema che esegue Linux.
• Accesso alla riga di comando/terminale.
• Un editor di testo, come Vi/Vim.

Come commentare in Bash

Quando si scrivono script bash, qualsiasi testo dopo un segno hash (# ) indica l'inizio di un commento e qualsiasi testo dopo # nella stessa riga non viene eseguito.

Quando si utilizza un editor di testo o un IDE, i commenti sono colorati in modo diverso dal resto del codice. Sono facili da notare e da cercare in codici più estesi.

L'unica eccezione è lo shebang (#! ), che si trova in genere sulla prima riga dello script. Shebang dice al sistema operativo quale interprete utilizzare per il codice.

I commenti in linea dopo lo shebang danno come risultato "Nessun file o directory di questo tipo " errore.

Riga singola e commento Bash in linea

Sia i commenti a riga singola che quelli inline negli script bash iniziano con il segno hash (# ):

# This is a comment

Lo spazio aggiuntivo dopo il segno non è necessario. Tuttavia, aiuta con la leggibilità.

Segui l'esempio seguente per creare uno script con commenti:

1. Apri il terminale (CTRL +ALT +T ) e creare uno script utilizzando Vi:

vi comment.sh

2. Aggiungi il seguente codice:

# 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.

Lo script include le seguenti righe:

• Riga 1 è un commento Bash a riga singola. Visivamente, l'istruzione si estende su due righe.
• Riga 2 è lo shebang. Lo script viene eseguito utilizzando l'interprete della shell Bash, che si trova in /bin/bash .
• Righe 3 e 5 sono anche commenti a riga singola prima e dopo un comando, rispettivamente.
• Riga 4 è un semplice comando eco con un commento in linea.

3. Salva e chiudi Vi:

:wq

4. Modifica le autorizzazioni dello script in eseguibile:

chmod +x comment.sh

5. Infine, esegui lo script con:

./comment.sh

I commenti non vengono visualizzati durante l'esecuzione dello script .

Commento Bash multilinea e blocco

Per creare commenti bash su più righe, inizia ogni riga con il segno cancelletto (# ):

# This is the first line
# This is the second line

Un altro modo non convenzionale per creare commenti a blocchi multilinea consiste nell'usare il comando bash null (: ) insieme alla notazione heredoc:

: << 'COMMENT'
This is the first line
This is the second line
COMMENT

Fondamentalmente, bash non supporta i commenti a blocchi. Questo metodo funziona come un hack se un commento di blocco è essenziale per un caso specifico.

Prova l'esempio seguente per vedere come funzionano i commenti multilinea e di blocco negli script bash:

1. Apri il terminale (CTRL +ALT +T ) e crea uno script di shell usando Vi:

vi multiline.sh

2. Copia e incolla il seguente codice:

: << '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.

Il codice esegue le seguenti operazioni:

• Riga 1 e 5 sono i delimitatori heredoc.
• Righe 2-4 sono i contenuti del commento del blocco.
• Riga 6 è l'echo comando.
• Righe 7-8 sono più commenti a riga singola, che fungono da commenti a più righe.

3. Salva il file e chiudi Vi:

:wq

4. Modifica le autorizzazioni dello script in eseguibile:

chmod +x multiline.sh

5. Infine, esegui lo script per vedere l'output:

./multiline.sh

L'output del terminale mostra solo il risultato in echo comando, mentre le righe commentate non vengono visualizzate.

Best practice e suggerimenti per i commenti Bash

Sebbene non ci siano regole specifiche per commentare in bash, alcune pratiche sono utili quando si usano i commenti. Queste pratiche e suggerimenti intendono aiutarti a ottenere il massimo dai commenti in bash.

1. Includi un'intestazione di file

Tutti gli script che non sono così evidenti a prima vista dovrebbero includere un'intestazione di file. L'intestazione ha diversi scopi:

• Spiega a colpo d'occhio cosa fa il codice.
• Indica la paternità.
• Spiega l'avviso di licenza e fornisce la dichiarazione di autorizzazione per il codice protetto da copyright.

Usa i commenti all'inizio di un codice per spiegare questi punti. Inoltre, se un codice fa parte di un progetto, includi il nome del progetto.

2. Evita i commenti bloccati non convenzionali

Sebbene i commenti di blocco siano possibili negli script bash, è una cattiva abitudine usarli. Il codice non è facilmente visibile come un normale commento perché gli editor di testo non li rendono come commenti. Inoltre, la ricerca è molto più semplice quando è presente una sintassi di commento unificata.

3. Evita commenti lunghi e inutili

Mantieni i commenti il ​​più brevi possibile e al punto. La verbosità non è necessaria e rende il codice più difficile da leggere.

Allo stesso modo, commenta solo il codice che è difficile da capire. Un commento su un semplice echo comando non è necessario, mentre il codice che utilizza un'istruzione regex complessa richiede una rapida indicazione di ciò che fa.

4. Commenti e funzioni

Tutte le funzioni bash beneficiano di commenti che spiegano lo scopo, gli input e gli output previsti. L'eccezione sono brevi pezzi di codice che sono evidenti.

Indicare quanto segue per ciascuna funzione:

• Breve descrizione dell'operazione.
• Un elenco di variabili globali o modificate.
• Gli argomenti di input previsti.
• Ciò che il processo invia al terminale.
• I valori di ritorno previsti.

Di seguito è riportato un esempio di una funzione che documenta ciascuno dei punti precedenti:

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!"
}

Adatta l'esempio al tuo caso d'uso.

5. Etichetta in modo coerente

Utilizzare i commenti per etichettare il codice che deve essere migliorato, implementato o modificato. Crea un'etichetta di commento coerente per un'attività diversa per semplificare la ricerca nei commenti.

Ad esempio, inizia e termina ogni spiegazione di funzione con # FUNCTION BEGIN oppure aggiungi # TODO commenti per compiti futuri. Allo stesso modo, decidi le etichette che ti sembrano adatte e mantieni la coerenza per tutto il codice.