Commenter et documenter vos développements

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.

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

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

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▲

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

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

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▲

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

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▲

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

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.