Envoyé par
jopopmk
1. Introduire une variable explicative
Non, je vais pas rajouter une variable inutile.
Si vraiment on a besoin d'une explication alors un commentaire va très bien.
L'inconvénient des commentaires, c'est de risquer de ne pas être à jour par rapport au code.
En particulier, quand le code est mis à jour par des développeurs trop pressés, on peut se retrouver avec des absurdités du style :
Sleep(3000); // Attendre 2 secondes.
qui peuvent être évitées avec une variable intermédiaire :
1 2
| const DWORD durationMilliseconds = 3000;
Sleep(durationMilliseconds); |
Envoyé par
jopopmk
2. Extraire une méthode
Toujours non, je vais pas empiler des appels inutiles.
Si vraiment on a besoin d'une explication alors un commentaire va très bien.
Nous sommes peut-être d'accord.
Il est pertinent de créer une sous-fonction dans les deux cas suivants :
- La sous-fonction est appelée dans plusieurs fonctions différentes. On évite alors les copiés-collés.
- La fonction appelante devient trop grosse. Pour qu'on puisse la comprendre facilement de manière globale, il faut déplacer une partie de son code dans des sous-fonctions avec un nom parlant.
Cela dit, si une fonction de taille modeste contient un ou deux bouts de code que je souhaite commenter et que ces bouts de code n'existent pas ailleurs, je ne vais pas les transformer en sous-fonctions seulement pour éviter d'écrire des commentaires !
L'inconvénient de morceler en sous-fonctions, c'est qu'il faut faire des aller-retours dans le code si on veut voir l'implémentation de ces sous-fonctions.
Envoyé par
jopopmk
3. Utiliser un nom d'identificateur plus descriptif
Là c'est assez évident. Maintenant il peut arriver qu'on se retrouve avec des noms sans fin, on peut alors contextualiser les variables avec un petit commentaire (dans l'exemple, en tête d'algo, indiquer "all sizes in pixels" ).
Je suis d'accord.
Envoyé par
jopopmk
4. Ajouter un contrôle dans le cas où votre code a des hypothèses
Gné ? Faire du défensif pour économiser un commentaire ? Là je sais même pas quoi dire ...
Faire du défensif ne sert pas à éviter les commentaires, mais à détecter les erreurs à l'exécution.
Cependant, puisqu'une instruction telle que checkArgument(height > 0); indique déjà clairement la précondition de la fonction, il est inutile de rappeler en plus cette précondition sous la forme d'un commentaire.
Envoyé par
Michael Guilloux
Quelles règles observez-vous pour insérer des commentaires dans votre code ?
J'écris des commentaires dans les cas suivants :
- Expliquer un choix, surtout s'il paraît étrange à un lecteur qui ne connaît pas le contexte.
- Résumer en quelques mots ce que fait une fonction ou ce que représente une classe, sauf si le nom de la fonction ou de la classe est déjà un résumé satisfaisant.
Le rôle du résumé est d'éviter d'obliger le lecteur à plonger dans le code s'il a besoin d'une information plus précise que le nom de la fonction ou de la classe mais pas forcément aussi précise que le code.
De même, il m'arrive parfois de résumer sous forme de commentaire ce que fait un bloc de code dans les cas où il n'est pas pertinent de déplacer ce bloc de code dans une sous-fonction (voir ci-avant). - Avertir sur les dangers d'une certaine fonction ou classe. Exemple : Attention, le bogue machin du ticket n°XXXX n'a pas encore été corrigé.
- Écrire parfois quelques "rappels" techniques si le lecteur a des chances de ne pas les avoir. Cela rejoint d'une certaine manière ce que disait BugFactory, mais ça ne s'applique pas qu'aux stagiaires. Cela s'applique aussi si on fait appel à des subtilités d'un langage ou d'une bibliothèque. Par exemple, en C++, il m'arrive d'écrire un commentaire du genre :
1 2 3 4
| // Rappel : propriétés de l'initialisation d'une variable locale statique :
// - Si l'initialisation lance une exception, elle est considérée comme non faite et
// sera retentée au prochain passage.
// - L'initialisation est thread-safe depuis C++11. |
- Mettre en évidence qu'un certain détail d'implémentation ne fait pas partie de l'interface.
Par exemple, dans une certaine classe, l'implémentation actuelle utilise un certain type de tableau associatif sous forme d'arbre binaire de recherche qui trie les éléments dans l'ordre des clés, mais l'implémentation future pourrait utiliser une table de hashage sans ce tri. Alors, dans l'interface de la classe, il vaut mieux avertir sous forme de commentaire : attention, ne vous reposez pas sur l'hypothèse que les éléments sont triés dans l'ordre des clés, car ça pourrait changer plus tard. - Aider l'utilisateur qui explore le code avec des commentaires de type "voir aussi telle fonction ou telle classe". Par exemple, quand il y a plusieurs fonction similaires (mais différentes), ce genre de commentaire aide l'utilisateur à trouver la bonne fonction à appeler.
Cela dit, comme je l'ai précisé, je suis conscient que, l'inconvénient des commentaires, c'est de risquer de ne pas être à jour par rapport au code. Du coup, quand une fonction a un code très simple et très petit, je préfère que la doc soit le code.
Par exemple, en C++, pour éviter d'écrire certaines préconditions et post-conditions sous forme de commentaires, il m'arrive de créer des fonctions en ligne qui ressemblent à :
1 2 3 4 5 6 7
| double my_sqrt(double param) {
assert(param >= 0);
double result = my_sqrt_impl(param);
assert(result >= 0);
return result;
}
// Rq : Dans du vrai code, je ne réimplémente pas sqrt, mais c'est pour l'exemple. |
et, pour décrire les invariants d'une classe, il m'arrive de créer une fonction membre :
1 2 3
| bool invariant() const {
// code qui retourne true si les invariants de la classe sont respectés
} |
Du coup, je configure l'outil de génération de code (dans mon cas, Doxygen) pour afficher aussi le code des fonctions. L'inconvénient est que l'ensemble des fichiers générés pour la documentation est assez volumineux.
Partager