Commenter et documenter vos développements

Sébastien MERIC

Dans cet article, je vous donne quelques idées pour vous aider dans votre difficile tâche de documentation technique. C'est un point sensible pour les développeurs qui ont toujours l'impression de perdre leur temps dans cette activité. J'essaye de vous montrer que le commentaire est essentiel à la lisibilité du code, donc a sa robustesse en général, et je vous donne quelques points de départ pour que le commentaire devienne pour vous un réflexe plutôt qu'une contrainte. ♪

- Titre : Commenter et documenter vos développements

- Auteur : Sébastien MERIC

- Parution : 12 novembre 2002

- Mise à jour : 2 mai 2013

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2013 Sébastien MERIC. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Introduction

- II. Règles

- II-A. Choisir un style de commentaire pour chaque type de commentaires

- II-B. Écrire les javadoc avant d'écrire le code

- II-C. Bien écrire les javadoc

- II-D. Ne pas noyer le code sous les commentaires

- II-D-1. Commentez toutes les branches conditionnelles

- II-D-2. Commentez toutes les boucles

- II-D-3. Commentez toutes les variables locales

- II-D-4. N'ajoutez pas de commentaires décoratifs

- II-E. Faites respirer votre code

- II-E-1. Mettez des espaces autour des opérateurs et des ponctuations

- II-E-2. Ajoutez des lignes vides

- III. Conclusion

- IV. Glossaire

- IV-A. Javadoc

I - Introduction

Commenter et documenter son code est une tâche qui paraît très difficile à mettre en œuvre au commun des développeurs. La réponse la plus fréquente avancée par ceux qui ne veulent, n'aiment, ou ne savent pas commenter leur code est, bien entendu, le peu de temps dont ils disposent pour développer. La réponse est erronée, mais il est important de comprendre pourquoi. Tous les articles que je vous propose vous parlent d'améliorer la robustesse du code. Cette robustesse passe par sa lisibilité. Bien entendu, la lisibilité est souvent mise en avant pour les développements futurs, du coup on se dit que la documentation peut bien attendre la fin du développement. Mais la lisibilité du code vous apporte surtout une meilleure compréhension de votre code, donc une robustesse accrue ! Il est donc hors de question de reporter à plus tard. En effet, pourquoi fournir un travail qui ne vous servirait pas à vous aussi, puisque c'est possible ?

Voilà donc une première bonne raison de documenter son code : le rendre lisible pour soi.

Une deuxième bonne raison : comprendre ce que l'on va écrire. En effet, écrire la javadoc avant de coder vous permet d'analyser votre besoin. Comme la granularité de cette analyse est très fine, ce sera de plus un bon point de départ pour améliorer votre aptitude à l'analyse.

Enfin, documenter son code c'est aussi évidemment le rendre lisible pour les autres, et quoi qu'on en dise, savoir qu'autrui utilise votre code flatte l'égo.

Pourtant, documenter le code est une chose difficile, car il ne faut dire que l'essentiel, sans noyer le code, ni vous-même, sous des tonnes de commentaires. Pour ce faire, quelques petites règles simples peuvent aider à démarrer un commentaire efficace.

II - Règles

II-A - Choisir un style de commentaire pour chaque type de commentaires

Par exemple,  en java il existe trois types de commentaires : le javadoc /** */ le commentaire multiligne /* */ et le commentaire uniligne //. Pour le commentaire javadoc, on n'a pas le choix. Par contre, les deux autres types de commentaires sont interchangeables et souvent utilisés selon l'humeur du moment. Pourtant, invalider momentanément des lignes de code boguées et ajouter un commentaire dans le code sont deux choses totalement différentes qui méritent d'être visualisées différemment.

Le commentaire /* */ étant multiligne, j'aurais tendance à le choisir pour la mise hors d'usage de lignes de codes.

De  plus, le // se prêtant très bien à un commentaire de fin de ligne, je le choisis plus volontiers pour les commentaires ajoutés au code.

Mais ceci dépend aussi de votre environnement ; en effet, si vous utilisez l'IDE JBuilder , le raccourci clavier [CTRL] + j ajoute ou supprime un // devant votre ligne ou devant le bloc de lignes sélectionnées. Ceci rend l'utilisation du // pour mettre le code hors d'usage plus simple, et vous permet donc de choisir /* */ pour les commentaires.

II-B - Écrire les javadoc avant d'écrire le code

Écrire les javadoc avant d'écrire le code permet deux choses fondamentales :

- vous les écrivez effectivement !

- vous prenez le temps d'analyser ce que vous allez écrire avant de foncer tête baissée vers le premier mur qui va se présenter.

II-C - Bien écrire les javadoc

Bien écrire un javadoc commence déjà par une connaissance fine de l'API. Un petit résumé s'impose :

- le javadoc se décompose en trois parties : le résumé, le corps et le tag. Le texte dans ces parties peut être entièrement formaté en html ;

- le résumé commence au début du javadoc et se termine au premier point rencontré ;

- le corps commence au début du javadoc (le résumé est repris) et se termine au premier tag rencontré ;

- les tags se décomposent en général en trois ou quatre parties : le tag lui-même, une référence éventuelle, le résumé et le corps @tag variable résumé jusqu'ici. <p>Corps du doc et se termine soit à la fin du javadoc, soit sur le prochain tag.

Pour une méthode, il est nécessaire dans le javadoc de faire figurer :

- le résumé descriptif de la classe (pensez à mettre le point) ;

- le corps de description, comprenant en particulier les contraintes pré et posttraitement ;

- une description de chaque paramètre, avec en particulier, un résumé (pensez au point) ; éventuellement un corps, les contraintes sur l'argument ;

- la valeur retournée s'il y en a une ;

- une description de toutes les exceptions que peut lancer la méthode.

Il est utile dans le javadoc d'une méthode de faire figurer :

- un exemple d'utilisation (on le remplacera avantageusement par les tests unitaires dans un article à venir).

II-D - Ne pas noyer le code sous les commentaires

Paradoxalement, trop de commentaires tuent le code autant que le manque total de commentaires. Pour éviter de tomber dans le piège du tout ou rien, il est intéressant de se fixer quelques règles afin d'acquérir des automatismes.

II-D-1 - Commentez toutes les branches conditionnelles

if (null == maChaine) { // on affiche "" plutôt que null pour une chaine vide
maChaine = "";
}

II-D-2 - Commentez toutes les boucles

Iterator i = getIterator();
while (i.hasNext()) {  // parcours la liste des utilisateurs à la recherche des comptes expirés
/* le code ici */
}

II-D-3 - Commentez toutes les variables locales

int nbUsers; // compteur d'utilisateurs
String mostActiveUser; // Nom de l'utilisateur le plus souvent connecté

II-D-4 - N'ajoutez pas de commentaires décoratifs

Les grosses décorations entre les méthodes du genre :

/****************************************************************/

ou les dessins de type :

/*
#   # #### ##### #   #  ##  ###  ####
## ## #      #   #   # #  # #  # #
# # # ##     #   ##### #  # #  # ##
#   # #      #   #   # #  # #  # #
#   # ####   #   #   #  ##  ###  ####
*/

Ne font qu'encombrer le code inutilement, d'autant qu'avec les javadoc, la séparation entre les méthodes est déjà bien assez claire.

II-E - Faites respirer votre code

La documentation du code ne s'arrête pas à quelques commentaires, ni même à des schémas et des documents externes au code. Le code lui-même doit être autodocumenté par une présentation propre, des noms de variables et de méthodes significatifs, le respect de règles typographiques.

II-E-1 - Mettez des espaces autour des opérateurs et des ponctuations

Comparez les codes suivants :

a=5+(6*b)-c;

a = 5 + (6 * b) - c
if(null==var){// var est null on s'arrête
return;
}

if (null == var) { // var est null on s'arrête
return;
}

Les règles à suivre ici sont simples :

1. Mettre des espaces autour des opérateurs, ex. : + - * / & && == = ;

2. Suivre les règles de dactylographie c'est-à-dire :

1. Pour les ponctuations à 1 signe ex. . , pas d'espace avant et un espace après,

2. Pour les ponctuations à deux signes ex. : ; ? ! mettre un espace avant et après,

3. Enfin pour les parenthèses, crochets ou accolades : un espace à l'extérieur et pas d'espace à l'intérieur.

Il y a toutefois deux exceptions à ces règles :

1. Le point est un opérateur d'accès à un membre de classe, on ne met aucun espace autour ;

2. L'espace devant la parenthèse quand elle sert pour la  définition des paramètres à l'appel d'une méthode n'est pas nécessaire.

double f;
double x;
double a=5;
double b=2;
double min=0
double max=3;
for(int i=0; i<100; i++) {
x=min+i*max/100;
f=a*x*x+b;
drawLine(x,f);
}

double f; // résultat de la fonction a.x² + b
double x;
double a;
double b;
double min = 0;    // ordonnée minimum à affichée
double max = 3;    // ordonnée maximum à affichée
for (int i = 0 ; i < 100 ; i++) { // on découpe la courbe en 100 segments
x = min +( i * max / 100);  // recherche de la ième valeur de x dans pour l'affichage
f = a * x * x + b;
drawLine(x, f);
}

II-E-2 - Ajoutez des lignes vides

Mettre des lignes vides entre les différentes sections de votre code le rend beaucoup plus lisible. Pour vous en convaincre, voici encore un petit exemple :

double f;
double x;
double a=5;
double b=2;
double min=0
double max=3;
for(int i=0; i<100; i++) {
x=min+i*max/100;
f=a*x*x+b;
drawLine(x,f);
}

double f; // résultat de la fonction a.x² + b

double x;

double a;

double b;

double min = 0;    // ordonnée minimum à affichée

double max = 3;    // ordonnée maximum à affichée

for (int i = 0 ; i < 100 ; i++) { // on découpe la courbe en 100 segments
x = min +( i * max / 100);  // recherche de la ième valeur de x dans pour l'affichage
f = a * x * x + b;

drawLine(x, f);
}

III - Conclusion

Je vous ai présenté dans cet article quelques « bonnes pratiques » pour documenter son code. La liste n'est ni exhaustive, ni à suivre à la lettre. En effet, le plus important reste que votre code soit lisible. Retenez donc de cet article, qu'il faut commenter, que trop de commentaires pourraient bien avoir l'effet inverse de celui attendu, que le code s'autodocumente très bien si des règles sont préétablies et respectées. Choisissez vos règles, prenez dans l'article celles qui vous plaisent, et respectez-les scrupuleusement ! Et ne vous inquiétez pas, si les premiers temps, respecter les règles que l'on s'impose demande beaucoup d'attention, en moins de 15 jours, l'habitude remplacera la concentration.

IV - Glossaire

IV-A - Javadoc

Les javailleurs savent de quoi il s'agit, pour les autres, c'est juste un commentaire mis avant une classe, une méthode ou un attribut qui est extrait automatiquement pour une mise en page lisible à l'aide d'un outil.

Remarque pour les développeurs Delphi : au moins un utilitaire du type javadoc existe pour vous : Time2Help, il n'est pas gratuit ni open source mais très utile. Si vous en connaissez d'autres, faites-le-moi savoir. Pour les autres langages, merci aussi de me faire un MP.