Le problème n'est pas tant de savoir s'il faut commenter le code ou non — oui il faut commenter le code! — mais de savoir quelle information doivent véhiculer les commentaires.
Les commentaires qui paraphrasent le code sans rien expliquer ne servent à rien. Par exemple en C un commentaire de type
/* returnPointer(); Return a pointer. */my_structure*returnPointer();
comme on en voit souvent, ne sert à rien: il manque l'information cruciale: qui possède le pointeur?
Il faut toujours commenter le domaine des arguments acceptés, car en général le type seul ne permet pas déterminer le domaine de la fonction. Il faut aussi commenter les conditions d'erreur, particulièrement celles qui ne sont pas gérées. Les algorithmes doivent être commentés, sinon on n'y comprend rien! Les invariants doivent être écrits.
En gros, il suffit d'avoir de la sympathie pour la personne qu'on sera dans 3 mois qui devra déboguer le code et aura tout oublié! :)
P.S.: Sur la photo c'est quoi la fonte? On dirait Monaco mais je ne suis pas sûr à cause de la perspective. :)
# Bons commentaires
Posté par Michaël (site web personnel) . En réponse au journal To comment or not to comment. That is the question.. Évalué à 4.
Le problème n'est pas tant de savoir s'il faut commenter le code ou non — oui il faut commenter le code! — mais de savoir quelle information doivent véhiculer les commentaires.
Les commentaires qui paraphrasent le code sans rien expliquer ne servent à rien. Par exemple en C un commentaire de type
comme on en voit souvent, ne sert à rien: il manque l'information cruciale: qui possède le pointeur?
Il faut toujours commenter le domaine des arguments acceptés, car en général le type seul ne permet pas déterminer le domaine de la fonction. Il faut aussi commenter les conditions d'erreur, particulièrement celles qui ne sont pas gérées. Les algorithmes doivent être commentés, sinon on n'y comprend rien! Les invariants doivent être écrits.
En gros, il suffit d'avoir de la sympathie pour la personne qu'on sera dans 3 mois qui devra déboguer le code et aura tout oublié! :)
P.S.: Sur la photo c'est quoi la fonte? On dirait Monaco mais je ne suis pas sûr à cause de la perspective. :)