À retenir
- C'est un bloc de commentaires structuré placé en haut d'un fichier ou d'une fonction.
- Il sert de documentation interne pour les développeurs.
- Il contient généralement l'auteur, la date, le but du code et les licences éventuelles.
En programmation, un cartouche est un bloc de texte mis en commentaire qui sert de fiche d'identité à un fichier ou à une fonction. Il agit comme une étiquette explicative permettant de comprendre rapidement l'utilité d'un morceau de code sans avoir à l'analyser ligne par ligne.
Étymologie
Vient du latin charta signifiant « papier ». Initialement utilisé pour désigner un rouleau de papier ou un encadrement ornemental, le terme a évolué en informatique pour décrire un espace délimité (souvent par des symboles comme des astérisques) contenant des informations administratives sur le code.
Exemples d'usage
- Un bloc de commentaires au début d'un script Python indiquant le nom de l'auteur, la date de création et la version.
- Une description structurée juste au-dessus d'une fonction C++ expliquant ses paramètres d'entrée et sa valeur de retour.
Cas d'usage
Le cartouche est utilisé en développement logiciel pour faciliter la maintenance et le travail en équipe. Il permet aux développeurs qui reprennent un projet de savoir immédiatement qui contacter en cas de bug ou quel est le but précis d'un algorithme complexe.
Bonnes pratiques
Il est recommandé de rester concis et de mettre à jour le cartouche dès que le code est modifié. L'utilisation de formats standards (comme JSDoc ou Doxygen) est préférable, car ils permettent de générer automatiquement une documentation complète à partir de ces commentaires.
Synonymes
Antonymes
Conseil
Si vous débutez, prenez l'habitude de créer un petit cartouche standard pour vos projets : nom du projet, votre nom et une phrase expliquant l'objectif du fichier. C'est une excellente pratique professionnelle qui montre la rigueur de votre travail.
Questions fréquentes
Le cartouche est-il lu par l'ordinateur ?
Non, il est placé dans des balises de commentaires, ce qui signifie que l'ordinateur l'ignore totalement lors de l'exécution du programme.
Faut-il en mettre partout ?
Il est conseillé d'en mettre un par fichier et au-dessus des fonctions complexes. Pour les fonctions très simples et évidentes, cela peut parfois alourdir la lecture.