J'ai le sentiment que ce n'est pas forcément faisable, ni souhaitable, de commenter la totalité de son code. Par commenter la totalité de son code j'entends associer un commentaire type "javadoc" à chaque fonction/méthode que l'on code. D'autant que dans certains cas la valeur ajoutée est vraiment très faible. Quelle est l'utilité réelle de commentaires comme les suivants :
/** Computes the threshold based on the red component
* on the pixel with the highest red component in
* the picture
*
* @param maxRedValue
* The red component of the pixel with the highest red component
* @return the computed threshold
*/
double computeThreshold(int maxRedValue) {
...
}
/**
* Get the user ID
*
* @return the user ID
*/
int getID() {
...
}
Mieux vaut dépenser son temps à bien penser l'architecture de son application/refactoriser si nécessaire plutôt que de le perdre à écrire ce genre de commentaires. Un document expliquant l'architecture de l'application/la manière dont elle a été conçue et pensée sera bien plus utile à quelqu'un voulant la modifier que ce type de commentaires.
La situation est évidemment différent quand il s'agit d'API publiques. Dans ce cas, évidemment tout doit être précisément documenté sinon elles sont inutilisables et donc inutiles.
Il faut bien garder à l'esprit qu'écrire des bons commentaires pour son code, c'est pas juste une bonne pratique, ça prend beaucoup, beaucoup de temps. D'autant plus qu'il faut maintenir les commentaires avec le code sinon ils font plus de mal que de bien. Je crois donc qu'on peut se passer de commentaires dans les classes utilisées en interne.
J'ai eu l'occasion de mettre les mains dans le code d'Hadoop et apparemment, c'est l'approche qu'ils ont choisi. Les classes utilisés en interne ne sont pas commentées (si ce n'est de petits commentaires pour indiquer des choses pas évidentes au premier coup d'œil). Les API publiques sont par contre parfaitement documentées.
# La bonne question serait plutôt : Que commentez-vous ?
Posté par X345 . En réponse au sondage Les commentaires et vous ?. Évalué à 7.
J'ai le sentiment que ce n'est pas forcément faisable, ni souhaitable, de commenter la totalité de son code. Par commenter la totalité de son code j'entends associer un commentaire type "javadoc" à chaque fonction/méthode que l'on code. D'autant que dans certains cas la valeur ajoutée est vraiment très faible. Quelle est l'utilité réelle de commentaires comme les suivants :
Mieux vaut dépenser son temps à bien penser l'architecture de son application/refactoriser si nécessaire plutôt que de le perdre à écrire ce genre de commentaires. Un document expliquant l'architecture de l'application/la manière dont elle a été conçue et pensée sera bien plus utile à quelqu'un voulant la modifier que ce type de commentaires.
La situation est évidemment différent quand il s'agit d'API publiques. Dans ce cas, évidemment tout doit être précisément documenté sinon elles sont inutilisables et donc inutiles.
Il faut bien garder à l'esprit qu'écrire des bons commentaires pour son code, c'est pas juste une bonne pratique, ça prend beaucoup, beaucoup de temps. D'autant plus qu'il faut maintenir les commentaires avec le code sinon ils font plus de mal que de bien. Je crois donc qu'on peut se passer de commentaires dans les classes utilisées en interne.
J'ai eu l'occasion de mettre les mains dans le code d'Hadoop et apparemment, c'est l'approche qu'ils ont choisi. Les classes utilisés en interne ne sont pas commentées (si ce n'est de petits commentaires pour indiquer des choses pas évidentes au premier coup d'œil). Les API publiques sont par contre parfaitement documentées.