Comment commenter dans Bash

Présentation

Les commentaires dans les scripts bash et la programmation en général aident à rendre un programme plus facile à comprendre. Lorsqu'un programme s'exécute, l'interpréteur ignore les lignes commentées. Cependant, les commentaires aident à la lisibilité globale du programme.

Lorsque vous regardez le code plus tard, il est utile d'avoir des explications descriptives et précieuses sur ce que fait le code. Commenter le code pour une utilisation ultérieure est une pratique courante et constitue une partie essentielle de la programmation et des scripts bash.

Ce tutoriel montre comment utiliser les commentaires et les meilleures pratiques de commentaires dans les scripts bash.

Prérequis

Un système exécutant Linux.
Accès à la ligne de commande/au terminal.
Un éditeur de texte, tel que Vi/Vim.

Comment commenter dans Bash

Lors de l'écriture de scripts bash, tout texte après un signe dièse (# ) indique le début d'un commentaire et tout texte après # dans la même ligne ne s'exécute pas.

Lorsque vous utilisez un éditeur de texte ou un IDE, les commentaires sont colorés différemment du reste du code. Ils sont faciles à remarquer et à rechercher dans des codes plus étendus.

La seule exception est le shebang (#! ), qui se trouve généralement sur la première ligne du script. Le shebang indique au système d'exploitation quel interpréteur utiliser pour le code.

Les commentaires en ligne après le shebang entraînent un "Aucun fichier ou répertoire de ce type " erreur.

Commentaire sur une seule ligne et en ligne sur le bash

Les commentaires sur une seule ligne et en ligne dans les scripts bash commencent par le signe dièse (# ):

# This is a comment

L'espace supplémentaire après le signe n'est pas nécessaire. Cependant, cela aide à la lisibilité.

Suivez l'exemple ci-dessous pour créer un script avec des commentaires :

1. Ouvrez le terminal (CTRL +ALT +T ) et créez un script en utilisant Vi :

vi comment.sh

2. Ajoutez le code suivant :

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

Le script comprend les lignes suivantes :

Ligne 1 est un commentaire Bash d'une seule ligne. Visuellement, la déclaration s'étend sur deux lignes.
Ligne 2 est le shebang. Le script s'exécute à l'aide de l'interpréteur de shell Bash, situé dans /bin/bash .
Lignes 3 et 5 sont également des commentaires sur une seule ligne avant et après une commande, respectivement.
Ligne 4 est une simple commande echo avec un commentaire en ligne.

3. Enregistrez et fermez Vi :

:wq

4. Modifiez les autorisations du script en exécutable :

chmod +x comment.sh

5. Enfin, exécutez le script avec :

./comment.sh

Les commentaires ne s'affichent pas lors de l'exécution du script .

Commentaire multiligne et bloc Bash

Pour créer des commentaires bash multilignes, commencez chaque ligne par le signe dièse (# ):

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

Une autre façon non conventionnelle de créer des commentaires de blocs multilignes consiste à utiliser la commande bash null (: ) avec la notation heredoc :

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

Fondamentalement, bash ne prend pas en charge les commentaires de bloc. Cette méthode fonctionne comme un hack si un commentaire de bloc est essentiel pour un cas spécifique.

Essayez l'exemple ci-dessous pour voir comment les commentaires multilignes et de bloc fonctionnent dans les scripts bash :

1. Ouvrez le terminal (CTRL +ALT +T ) et créez un script shell en utilisant Vi :

vi multiline.sh

2. Copiez et collez le code suivant :

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

Le code fait ce qui suit :

Lignes 1 et 5 sont les délimiteurs heredoc.
Lignes 2 à 4 sont le contenu du commentaire de bloc.
Ligne 6 est l'echo commande.
Lignes 7-8 sont plusieurs commentaires sur une seule ligne, qui agissent comme des commentaires multilignes.

3. Enregistrez le fichier et fermez Vi :

:wq

4. Modifiez les autorisations du script en exécutable :

chmod +x multiline.sh

5. Enfin, exécutez le script pour voir le résultat :

./multiline.sh

La sortie du terminal affiche uniquement le résultat dans le echo commande, tandis que les lignes commentées ne s'affichent pas.

Meilleures pratiques et astuces pour les commentaires Bash

Bien qu'il n'y ait pas de règles spécifiques pour les commentaires dans bash, certaines pratiques sont utiles lors de l'utilisation des commentaires. Ces pratiques et conseils ont pour but de vous aider à tirer le meilleur parti des commentaires dans bash.

1. Inclure un en-tête de fichier

Tous les scripts qui ne sont pas aussi apparents à première vue doivent inclure un en-tête de fichier. L'en-tête a plusieurs objectifs :

Explique ce que fait le code en un coup d'œil.
Indique la paternité.
Explique l'avis de licence et fournit la déclaration d'autorisation pour le code protégé par des droits d'auteur.

Utilisez des commentaires au début d'un code pour expliquer ces points. De plus, si un code fait partie d'un projet, incluez le nom du projet.

2. Évitez les commentaires de bloc non conventionnels

Bien que les commentaires de bloc soient possibles dans les scripts bash, c'est une mauvaise habitude de les utiliser. Le code n'est pas aussi facilement perceptible qu'un commentaire normal car les éditeurs de texte ne les rendent pas sous forme de commentaires. De plus, la recherche est beaucoup plus facile lorsqu'il existe une syntaxe de commentaire unifiée.

3. Évitez les commentaires longs et inutiles

Gardez les commentaires aussi courts que possible et précis. La verbosité est inutile et rend le code plus difficile à lire.

De même, ne commentez que le code difficile à saisir. Un commentaire sur un simple echo commande n'est pas nécessaire, alors que le code qui utilise une instruction regex complexe nécessite une indication rapide de ce qu'il fait.

4. Commentaires et fonctions

Toutes les fonctions bash bénéficient de commentaires qui expliquent le but, les entrées et les sorties attendues. L'exception est de courts morceaux de code qui sont apparents.

Indiquez ce qui suit pour chaque fonction :

Brève description de l'opération.
Une liste de variables globales ou modifiées.
Les arguments d'entrée attendus.
Ce que le processus affiche sur le terminal.
Les valeurs de retour attendues.

Ci-dessous un exemple de fonction qui documente chacun des points précédents :

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

Ajustez l'exemple à votre cas d'utilisation.

5. Étiqueter de manière cohérente

Utilisez des commentaires pour étiqueter le code qui doit être amélioré, implémenté ou modifié. Créez une étiquette de commentaire cohérente pour une tâche différente afin de faciliter la recherche dans les commentaires.

Par exemple, commencez et terminez chaque explication de fonction par # FUNCTION BEGIN , ou ajoutez # TODO commentaires pour les tâches futures. De même, décidez quelles étiquettes vous semblent appropriées et restez cohérentes tout au long du code.