====== Bash : Le caractère pour commenter ====== * Objet : Présentation du caractère pour commenter dans Bash; * Niveau requis : {{tag>débutant}} * Pour aller vers : {{tag>avisé}} * Commentaires : Pour l'interpréteur de commande bash (et zsh aussi). * Débutant, à savoir : [[:doc:systeme:commandes:le_debianiste_qui_papillonne|Utiliser GNU/Linux en ligne de commande, tout commence là !.]] :-) * Suivi : {{tag>en-chantier à-tester}} * Création par [[user>agp91]] le 23/06/2024 * Testé par <...> le <...> FIXME * Commentaires sur le forum : [[https://debian-facile.org/viewtopic.php?pid=416009| Lien vers le forum concernant ce tuto]] ((N'hésitez pas à y faire part de vos remarques, succès, améliorations ou échecs !)) **Nota :** Contributeurs, les FIXME sont là pour vous aider, supprimez-les une fois le problème corrigé ou le champ rempli ! ===== Introduction ===== 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. ==== Présentation ==== 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. ===== Descriptions ===== //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é((La protection de caractère ou de mots réservés indique à //bash// de ne pas interpréter ce qui est protégé comme élément de sa syntaxe.\\ Voir : [[atelier:chantier:bash:les-caracteres-de-protection|Bash : Les caractères de protection]])) et si l'option ''interactive_comments'' n'est pas désactivée (voir section [[#exceptions|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. ===== Usages ===== 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((Les **blancs** sont les espaces et les tabulation.\\ Voir ''man bash'' section DÉFINITIONS.)) 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 :\\ '' '' //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. ===== Alternatives ===== 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 **'':''**((La commande **'':''** (deux points) est une commande interne de l'interpréteur //bash//. Elle ne fait rien d'autre que de développer les arguments et redirection qui la suive.\\ Voir ''man bash'' section COMMANDES INTERNES DE L'INTERPRÉTEUR.)) : 'Ceci passe Pour être un commentaire Sur plusieurs lignes' Ou avec l'opérateur de redirection **''<<''**((L'opérateur de redirection **''<<''**, nommé **document en ligne** (//herdoc// en anglais), permet de rediriger l'entrée de l'interpréteur depuis la source actuelle (la ligne de commande ou depuis le script exécuté).\\ Voir ''man bash'' section REDIRECTION > Document en ligne.)) << '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#' ''. * Ou de les supprimer dans un affichage du code.\\ Contrairement à un simple ''grep -Ev '^#| #|'$'\t#' ''. 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,\\ LOL 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. ===== Exceptions ===== 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 : ** !#**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 ===== Conclusions ===== É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. Toutes fois,\\ Les pseudos alternatives décrites plus haut sont pratiques durant la phase de développement d'un script.\\ Non pas pour réaliser des commentaires.\\ Mais dans le cas où il est nécessaire d'inhiber un grand bloc de code.\\ Évitant ainsi d'insérer devant chaque lignes à inhiber le caractère ''#''.