Sur le principe oui, mais je ne comprend vraiment pas cette histoire de zéro doc. Je crois que j'en avais parlé dans un autre journal mais j'ai un vrai problème avec.
Qu'il y ait vraiment peu de doc type javadoc d'API pourquoi pas. Mais zéro commentaire montre en général que la fonction d'un commentaire n'est pas comprise du tout.
Déjà parce que certains algos ne peuvent être forcément totalement évidents (et il vaut mieux dans ce cas garder l'explication au plus proche du code).
Mais aussi parce que nombre de commentaires devraient non pas expliquer le code (là c'est probablement qu'il faut le réecrire) mais expliquer ce qui n'y est pas et qui est parfois même plus important que le code en lui-même : l'intention.
C'est l'intention qui permet parfois de différentier un bug d'un comportement spécifique. Et ça, sans explication de l'intention pas moyen de le savoir.
Donc oui, la doc obsolète c'est mal. Et les générateurs de doc encouragent la doc idiote. Mais zéro doc est à mon avis aussi dangereuse.
C'est pour ça que j'aime bien, entre autre, le literate programming dans le sens où on lie vraiment les deux, et c'est pour ça aussi qu'il est absolument obligatoire de commenter en anglais (car commenter if value is 2 en anglais ça revient tellement au même qu'on ferait de la duplication. Le commentaire dans une autre langue poserait malheureusement moins de problème et donc inciterait à avoir des commentaires inutiles)
[^] # Re: La doc est toujours utile
Posté par CrEv (site web personnel) . En réponse au journal De tout, de rien, des liens, bla bla bla. Évalué à 3.
Sur le principe oui, mais je ne comprend vraiment pas cette histoire de zéro doc. Je crois que j'en avais parlé dans un autre journal mais j'ai un vrai problème avec.
Qu'il y ait vraiment peu de doc type javadoc d'API pourquoi pas. Mais zéro commentaire montre en général que la fonction d'un commentaire n'est pas comprise du tout.
Déjà parce que certains algos ne peuvent être forcément totalement évidents (et il vaut mieux dans ce cas garder l'explication au plus proche du code).
Mais aussi parce que nombre de commentaires devraient non pas expliquer le code (là c'est probablement qu'il faut le réecrire) mais expliquer ce qui n'y est pas et qui est parfois même plus important que le code en lui-même : l'intention.
C'est l'intention qui permet parfois de différentier un bug d'un comportement spécifique. Et ça, sans explication de l'intention pas moyen de le savoir.
Donc oui, la doc obsolète c'est mal. Et les générateurs de doc encouragent la doc idiote. Mais zéro doc est à mon avis aussi dangereuse.
C'est pour ça que j'aime bien, entre autre, le literate programming dans le sens où on lie vraiment les deux, et c'est pour ça aussi qu'il est absolument obligatoire de commenter en anglais (car commenter
if value is 2en anglais ça revient tellement au même qu'on ferait de la duplication. Le commentaire dans une autre langue poserait malheureusement moins de problème et donc inciterait à avoir des commentaires inutiles)