• Objet : Présentation du caractère pour commenter dans Bash;
• Niveau requis :

  débutant
• Pour aller vers :

  avisé
• Commentaires : Pour l'interpréteur de commande bash (et zsh aussi).
• Débutant, à savoir : Utiliser GNU/Linux en ligne de commande, tout commence là !.
• Suivi :

  en-chantier, à-tester
  • Création par agp91 le 23/06/2024
  • Testé par <…> le <…>
• Commentaires sur le forum : Lien vers le forum concernant ce tuto ¹⁾

Nota :

Contributeurs, les sont là pour vous aider, supprimez-les une fois le problème corrigé ou le champ rempli !

Dans un script,
Les commentaires permettent de faire des annotations sur le code écrit.
D'y apporter des explications, des notifications ou tout simplement des points de repères pour que le lecteur puisse s'y retrouver.

En ligne de commande (mode interactif), les commentaires sont souvent jugés inutiles.
Pourtant, ils permettent de mémoriser l'explication d'une ligne commande, rappelée par l'historique.
Ou d'y ajouter un tag personnel, afin de faciliter la recherche dans l'historique.

Ce tuto propose d'expliquer l'usage des commentaires dans l'interpréteur de commande Bash.
Seront aussi montrés, l'écriture de pseudos (qui n'en sont pas) commentaires multi-lignes.

Bash ne dispose que d'un seul caractère pour introduire (composer) les commentaires.

Il s'agit du caractère #.

S'il n'est pas protégé²⁾ et si l'option interactive_comments n'est pas désactivée (voir section Exceptions plus bas),
Ce caractère commente tout ce qui le suit, jusqu'à la fin de la ligne.

Tout ce qui est commenté, est ignoré par bash durant l'interprétation.

Lors de l'exécution d'un script,
Bash commence par placer tout le code du script dans un tampon mémoire.
… Puis ce tampon est interprété.
Durant la lecture du fichier (le script), les commentaires sont ignorés.
Et ne sont donc pas placés, dans le tampon.

Les commentaires,
Commencent par le caractère #
Et se terminent à la fin de la ligne (jusqu'au saut de ligne).

Ce qui nous permet d'obtenir deux types de commentaires :

• La commentarisation d'une ligne entière.

# Commentaire d'une ligne entière

• Et les commentaires de fin de ligne (du caractère de commentarisation#, jusqu'à la fin de ligne).

echo "Debian Facile" # Commentaire de fin de ligne

Debian Facile

Pour écrire un commentaire de fin de ligne, un caractère blanc³⁾ est obligatoire devant le caractère # pour que bash le reconnaisse comme caractère marquant le début d’un commentaire.

ls# Ceci n est pas un commentaire de fin de ligne

bash: ls# : commande introuvable

Seul le saut de ligne met fin au commentaire débuté par #.
Ainsi, bash ne permet pas d'écrire un commentaire au milieu d'une ligne, dans le genre :
<commande> <COMMENTAIRE> <commande>

Bash n'offre pas non plus la possibilité d'écrire des commentaires multi-lignes.
Si ce n'est, qu'en commentant chaque ligne individuellement :

# Pour écrire un commentaire multi-ligne,
# Chaque lignes du commentaire,
# Doivent être individuellement commentées.

De nombreux sites proposent une alternative pour écrire des commentaires sans l'usage du caractère #.
Promettant même l'écriture de commentaires multi-lignes :

Avec la commande interne :⁴⁾

: 'Ceci passe
Pour être un commentaire
Sur plusieurs lignes'

Ou avec l'opérateur de redirection <<⁵⁾

<< 'COMMENTAIRE'
Ceci parait aussi
Être un commentaire
Sur plusieurs lignes
COMMENTAIRE

Ou avec la combinaison des deux :

: << 'COMMENTAIRE'
Mais ce ne sont pas des commentaires !
COMMENTAIRE

Pourtant ce ne sont pas des (véritables) commentaires.
Ce sont des commandes (et/ou redirections) bash, qui sont interprétées.
Certes elles ne produisent aucun rendu visuel, ni aucune erreur lors de l'interprétation.
Et permettent d'ajouter un texte quelconque dans un script sans impacts perceptibles.
Pourtant il y en a !

Mis à part que ces pseudos commentaires,

• Ne sont pas reconnus comme commentaire, par la colorisation syntaxique et ne peuvent donc être colorisés comme le sont les commentaires.
• Qu'il peut être difficiles de les extraire pour les afficher.
  Contrairement à un simple grep -E '^#| #|'$'\t#' <chemin_script>.
• Ou de les supprimer dans un affichage du code.
  Contrairement à un simple grep -Ev '^#| #|'$'\t#' <chemin_script>.

Il n'est pas conseillé de les utiliser.

Car n'étant pas des commentaires, mais des commandes,
Elles ne sont pas ignorées durant l'interprétation (comme l'est un véritable commentaire) et consomment des ressources pour rien.

Lors de la mise en tampon mémoire d'un script (avant son interprétation), ces commandes ne sont pas ignorées (puisqu'elles sont des commandes) et sont donc placées dans le tampon.

Il n'est pas évident de visualiser le contenu de ce tampon.
Mais pour mettre cela en évidence, nous pouvons utiliser une fonction, qui elle peut être affichée par la commande set.

fun() {
	# Ceci est un véritable commentaire
	# Sur plusieurs ligne
<< 'COMMENTAIRE'
Ceci n'est pas un commentaire.
Mais une commande, certes qui ne fait apparemment rien.
... Mais une commande quand même.
COMMENTAIRE
	echo $1 # Retourne le premier argument transmis
}

Notre fonction créée, utilisons la :

fun "Debian Facile"

Debian Facile

Bien tout ce passe comme si nous avons véritablement écrit un véritable commentaire multi-ligne.

Mais,
C'est du “Cana… Dry” (ça en a l'apparence, ça en a le goût, mais n'en est pas).

Voyons cela en demandant l'affichage de notre fonction mémorisée par bash :

set | grep -A9 "^fun ()"

fun () 
{ 
    <<'COMMENTAIRE'
Ceci n'est pas un commentaire.
Mais une commande, certes qui ne fait apparemment rien.
... Mais une commande quand même.
COMMENTAIRE

    echo $1
}

Nous pouvons constater que les véritables commentaires n'ont pas été reconduits dans l'écriture mémorisant la fonction.
Par-contre nous y retrouvons le pseudo commentaire, occupant ainsi une place en mémoire.

unset fun   # Suppression de la fonction fun.

En mode interactif, par défaut l'option de l'interpréteur interactive_comments est active.
Si elle est désactivée (avec le commande shopt), les commentaires ne sont plus autorisés.

shopt interactive_comments 

interactive_comments	on

… Les commentaire sont actifs.
Désactivons les :

shopt -u interactive_comments 

Et testons

# Test de commentaire

bash: # : commande introuvable

Effectivement :

shopt interactive_comments 

interactive_comments	off

Réactivons les commentaires :

shopt -s interactive_comments 

Le caractère # n'est pas reconnu comme introduisant un commentaire lorsqu'il est protégé, que ce soit par

• Le caractère de protection \ (contre oblique)
• Ou par l'encadrement entre guillemets (simples ou doubles)

Ou lorsque qu'il est utilisé dans d'autres usages que bash lui attribue :

• Dans le développement des paramètres, variables et tableaux :
  • Le paramètre spécial $# ou ${#} : Renvoie le nombre de paramètre positionnel.
  • ${p#motif} ou ${p##motif} : Supprime le préfixe motif du contenu du paramètre (ou de la variable) p
  • ${#var} ou ${#tab[indice]} : Renvoie le nombre de caractère contenu dans la variable var ou de l'élément indice du tableau tab.
  • ${#tab[*]} ou ${#tab[@]} : Renvoie le nombre d'éléments du tableau tab.
  • ${p/#motif/chaîne} : Substitue motif par chaîne si motif se trouve au début du contenu de p.
• Dans une évaluation arithmétique avec base#n où base indique la base numérique utilisée pour exprimer le nombre n.
• Dans l'écriture de l'invite, \# est remplacé lors du développement de l'invite par le numéro de la commande précédemment utilisée.
• Quand il est utilisé comme indicateur d'événement dans le développement de l'historique : <chaîne> !#Entrèe.

Remarques : Dans tous ces cas d'usages, le caractère # n'est pas précédé d'un blanc.
Il ne peut donc pas être reconnu comme commentaire de fin de ligne.

Le shebang, la première ligne d'un script, si elle débute par #!.
Pour le script en court d'exécution, c'est un commentaire.
Mais si bash doit appeler un autre script, le shebang (de cet autre script) désigne alors, l'interpréteur spécifié après #! (exemple : #!/bin/bash), que bash devra utiliser pour exécuter ce script.

Voir : man bash section EXÉCUTION DES COMMANDES

Écrire des commentaires dans un script (ou dans un code source), fait parti de l'art de bien écrire un programme.

Dans un script bash les commentaires apparaissent dès la première ligne, avec le shebang.
Vient généralement ensuite, commenté, ce que nous nommons l’entête du script. Il comporte divers informations tels que : La description du script, son auteur, sa date création, son numéro de version, etc.

Mais tous cela est relatif et dépend de l'auteur (chacun son art).
Par exemple certains préfèrent définir le numéro de version et la description dans des variables.
Utiliser une fonction pour décrire la syntaxe d'usage (pouvant ainsi être appelée lors de l'exécution du script avec par exemple l'option –help).

Le bon art évite les redondances.

Plus loin, les commentaires peuvent être utilisés pour structurer le code (mettre des points de repère explicites) afin de mieux s'y retrouver.
Expliquer des commandes complexes (dont la compréhension ne saute pas yeux).
Inhiber une partie du code sans devoir le supprimer.
Laisser des annotations de développement.
Etc.

Quoi qu'il en soit, les commentaires doivent être précis et concis.
Par exemple il est inutile de commenter une commande dont le nom est suffisamment explicite.
Mais là encore c'est relatif, par exemple lors de l'écriture d'un script pédagogique.
Et ils ne devraient pas être utilisés pour écrire une documentation complète (il y a d'autres voix pour cela).

Sans oublier qu'ils doivent être compréhensibles par d'autres afin de partager son code.
En ce sens il doivent être adaptés aux lecteurs ciblés.

Le mécanisme de commentarisation de bash est très simple.
Il utilise un seul caractère pour introduire (débuter) un commentaire, qui se poursuit jusqu’à la fin de ligne.
Ainsi nous pouvons commenter :

• Une (ou plusieurs) ligne(s) entière(s).
• Et à partir d'un certain endroit de la ligne, jusqu'à sa fin.

Cela est largement suffisant rendant inutile l'usage des pseudos alternatives.
Qui n'ont rien à voir avec les commentaires.