Commenter en Bash: Guide Complet pour les Débutants

Table des matières

Introduction

Les commentaires dans le script Bash, et plus généralement dans la programmation, aident à rendre un programme plus compréhensible. Lorsqu’un programme s’exécute, l’interpréteur ignore les lignes commentées. Cependant, les commentaires contribuent à la lisibilité globale du programme.

Lorsqu’on examine le code plus tard, il est utile d’avoir des explications descriptives et précieuses sur ce que fait le code. Mettre en commentaire du code pour une utilisation ultérieure est une pratique courante et fait partie intégrante de la programmation et de l’écriture de scripts Bash.

Ce tutoriel vous montre comment utiliser les commentaires et les meilleures pratiques de commentaire dans les scripts Bash.

Prérequis

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

Commenter en 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 # sur la même ligne n’est pas exécuté.

Lors de l’utilisation d’un éditeur de texte ou d’un IDE, les commentaires sont colorés différemment par rapport au reste du code. Ils sont faciles à repérer et à rechercher dans des codes plus longs.

Il y a cependant une exception avec le shebang (#!), qui est généralement placé à 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 une erreur “No such file or directory”.

Commentaire sur une seule ligne et en ligne

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

# Ceci est un commentaire

L’espace supplémentaire après le signe n’est pas nécessaire, mais il facilite la lisibilité.

Commentaire multilignes et en bloc

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

# Ceci est la première ligne
# Ceci est la deuxième ligne

Une autre façon peu conventionnelle de créer des commentaires en bloc est d’utiliser la commande nulle de Bash (:) avec la notation heredoc :

: << 'COMMENT'
Ceci est la première ligne
Ceci est la deuxième ligne
COMMENT

Fondamentalement, Bash ne prend pas en charge les commentaires en bloc. Cette méthode fonctionne comme une astuce si un commentaire en bloc est nécessaire pour un cas spécifique.

Essayez l’exemple ci-dessous pour voir comment les commentaires multilignes et en bloc fonctionnent dans les scripts Bash :

Ouvrez le terminal (CTRL+ALT+T) et créez un script shell avec Vi :

vi multiline.sh

Copiez et collez le code suivant :

: << 'COMMENT'
Ceci est un commentaire en bloc multiligne utilisant le heredoc avec des guillemets simples et la commande nulle de Bash.
COMMENT
echo "Bonjour le monde !"
# Ceci est un commentaire multiligne
# utilisant la notation sur une seule ligne.

Le code fait ce qui suit :

Les lignes 1 et 5 sont les délimiteurs du heredoc.
Les lignes 2 à 4 sont le contenu du commentaire en bloc.
La ligne 6 est la commande echo.
Les lignes 7 et 8 sont plusieurs commentaires sur une seule ligne, qui agissent comme des commentaires multilignes.

Enregistrez le fichier et fermez Vi :

:wq

Modifiez les permissions du script pour le rendre exécutable :

chmod +x multiline.sh

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

./multiline.sh

La sortie du terminal ne montre que le résultat de la commande echo, les lignes commentées n’apparaissent pas.

Meilleures pratiques et astuces pour les commentaires en Bash

Bien qu’il n’y ait pas de règles spécifiques pour les commentaires en Bash, certaines pratiques sont utiles lors de l’utilisation de commentaires. Ces pratiques et astuces visent à vous aider à tirer le meilleur parti des commentaires dans les scripts Bash.

1. Inclure un en-tête de fichier

Tous les scripts qui ne sont pas évidents à première vue devraient inclure un en-tête de fichier. L’en-tête remplit plusieurs fonctions :

Explique ce que fait le code en un coup d’œil.
Indique l’auteur.
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. Éviter les commentaires en bloc non conventionnels

Bien que les commentaires en bloc soient possibles dans les scripts Bash, il est préférable de les éviter. Le code n’est pas aussi facilement reconnaissable qu’un commentaire régulier car les éditeurs de texte ne les restituent pas comme des commentaires. De plus, la recherche est bien plus facile lorsqu’il y a une syntaxe de commentaire unifiée.

3. Éviter les commentaires longs et inutiles

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

De même, ne commentez que le code qui est difficile à comprendre. Un commentaire sur une simple commande echo est inutile, tandis qu’un code utilisant une expression régulière 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 arguments d’entrée et de sortie attendus. Exception faite pour les courts morceaux de code qui sont évidents.

Indiquez les éléments suivants pour chaque fonction :

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

Voici un exemple de fonction qui documente chacun des points précédents :

PREFIX="Bonjour "

#### DEBUT DE LA FONCTION
# Affiche une salutation
# VARIABLES GLOBALES :
# PREFIX
# ARGUMENTS :
# Nom en tant que chaîne de caractères à utiliser pour la salutation
# SORTIES :
# Écrit la chaîne sur STDOUT
# RÉSULTAT :
# 0 en cas de réussite, valeur non nulle sinon.
### FIN DE LA FONCTION
function () {
    echo "${PREFIX}: $1!"
}

Adaptez cet exemple à votre cas d’utilisation.

5. Étiqueter de manière cohérente

Utilisez des commentaires pour étiqueter le code qui nécessite une amélioration, une mise en œuvre ou une modification. 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 # DEBUT DE LA FONCTION, ou ajoutez des commentaires # TODO pour les tâches futures. De même, décidez des étiquettes qui semblent appropriées et restez cohérent tout au long du code.

Conclusion

Après avoir lu ce tutoriel, vous savez comment commenter en Bash. Suivez les astuces et les meilleures pratiques pour utiliser efficacement les commentaires dans vos scripts Bash.

DOCUMENT