À retenir
- Le contenu commenté est totalement ignoré par l'ordinateur lors de l'exécution.
- Elle facilite la lecture et la maintenance du code sur le long terme.
- Elle permet de documenter les intentions du développeur.
La commentarisation est l'action d'ajouter des notes explicatives à l'intérieur du code source d'un programme. C'est comme coller des post-it sur une recette de cuisine complexe pour expliquer certaines étapes aux futurs cuisiniers qui liront le document.
Étymologie
Dérivé du mot « commentaire », issu du latin commentarius (mémoire, note). Le suffixe « -isation » indique le passage à un état ou l'application d'un processus. En informatique, cela désigne l'action d'insérer des éléments textuels qui ne seront pas exécutés par la machine.
Exemples d'usage
- Expliquer une formule mathématique complexe au-dessus d'une fonction de calcul.
- Indiquer une tâche à réaliser plus tard avec la mention
// TODO: optimiser cette boucle. - Désactiver une portion de code suspectée de provoquer un bug sans pour autant la supprimer définitivement.
Cas d'usage
Ce concept est omniprésent dans le développement de logiciels, que ce soit pour le travail collaboratif (expliquer son code aux collègues) ou pour la maintenance personnelle (se souvenir de ses propres choix techniques six mois plus tard).
Bonnes pratiques
Il faut éviter de commenter l'évidence (par exemple : i = i + 1 // incrémente i). La règle d'or est d'expliquer le pourquoi plutôt que le comment. Un commentaire périmé qui ne correspond plus au code modifié est plus dangereux que pas de commentaire du tout.
Synonymes
Antonymes
Conseil
Essayez de rendre votre code le plus clair possible par lui-même (noms de variables explicites) pour limiter le besoin de commentarisation excessive. Utilisez les commentaires pour justifier des choix techniques qui ne sautent pas aux yeux.
Questions fréquentes
Est-ce que les commentaires alourdissent le logiciel final ?
Non. Dans la majorité des cas, les commentaires sont supprimés au moment de la compilation ou de la minification du code avant d'être envoyés à l'utilisateur.
Peut-on mettre n'importe quel caractère dans un commentaire ?
Oui, les commentaires acceptent généralement tous les caractères, y compris les accents et les emojis, car ils sont traités comme du texte pur.