Commenter et documenter vos développements
				12 Novembre 2002
				Version 1.0
				Par Sébastien MERIC
				Remerciements : Stefan Bertholon

Dans cet article, je vous donne quelques idées pour vous aider dans votre difficile tache 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 tobustesse en général, et je vous donne quelques points de départ pour que le commentaire devienne pour vous un reflexe plutôt qu'une contrainte.

Introduction

Commenter et documenter son code est une tâche qui paraît très difficile à mettre en oeuvre 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 évidement 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.

Règles

Choisir un style de commentaire pour chaque type de commentaires.

Par exemple,  en java il existe trois types de commentaires : le javadoc /** */ le commentaire multilignes /* */ 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 buggé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 multilignes, 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.

Ecrire les javadoc avant d'écrire le code

Ecrire 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.

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 3 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 3 ou 4 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 post-traitement,
• 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).

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.

Commentez toutes les branches conditionnelles

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

Commentez toutes les boucles

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

Commentez toutes les variables  locales

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

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.

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.

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 : 1 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.
   

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);
}

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 commentez, 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.

Glossaire

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 opensource 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.