Qu'est-ce que le code auto-documenté et peut-il remplacer un code bien documenté?

Question

J'ai un collègue qui insiste sur le fait que son code n'a pas besoin de commentaires, il est "auto-documentation."

J'ai passé en revue son code, et alors que c'est plus clair que le code que j'ai vu d'autres, produire, je suis toujours en désaccord que l'auto-documentation du code est aussi complète et utile aussi bien commenté et documenté code.

Aidez-moi à comprendre son point de vue.

• Qu'est-ce que l'auto documentation de code
• Peut-elle vraiment remplacer bien commenté et documenté code
• Existe-il des situations où il est mieux que bien documenté et commenté code
• Existe-il des exemples où le code ne peut pas être auto-documentation sans commentaires

Peut-être que c'est juste mes propres limites, mais je ne vois pas comment il peut être une bonne pratique.

Ce n'est pas censé être un argument s'il vous plaît ne pas les raisons pour lesquelles bien commenté et documenté code est prioritaire - de nombreuses ressources sont à apporter cette preuve, mais ils ne sont pas convaincants à mes pairs. Je crois que j'ai besoin de mieux comprendre son point de vue à le convaincre du contraire. Démarrer une nouvelle question, si vous devez, mais ne discute pas ici.

Wow, réponse rapide! Veuillez lire toutes les réponses et de fournir des commentaires aux réponses, plutôt que d'ajouter de nouvelles réponses, à moins que votre réponse est vraiment sensiblement différent de chaque autre réponse ici.

Aussi, ceux d'entre vous qui font valoir contre l'auto documentation de code -c'est surtout pour m'aider à comprendre le point de vue (c'est à dire, les aspects positifs) de l'auto-documentation du code des évangélistes. J'attends d'autres vont downvote vous si vous ne restez pas sur le sujet.

Answer 1

Eh bien, puisque c'est sur les commentaires et le code, regardons quelques-code. Comparer ce code par défaut:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

À cette auto-documentation du code, qui indique ce qui est fait:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2)

Et alors, à ce documenté code, ce qui explique mieux pourquoi il est fait:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2)

Et cet exemple de mauvais commentaires du style:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

Dans le dernier exemple, les observations sont utilisées lorsque les variables ont été descriptive nommé à la place, et les résultats de l'opération sont résumées où nous pouvons voir clairement ce que l'opération est. Je préfère l'auto-documenté deuxième exemple de ce tous les jours, et c'est peut-être ce que votre ami parle quand il dit que l'auto-documenté code.

Je dirais que ça dépend du contexte, de ce que vous faites. Pour moi, l'auto-documenté code est probablement suffisante dans ce cas, mais un commentaire détaillant la méthodologie derrière ce qui est derrière fait (dans cet exemple, l'équation) est également utile.

Answer 2

À mon avis, le code devrait être auto-documentation. En bonne, auto-documenté code, vous n'avez pas à expliquer chaque ligne unique parce que chaque identificateur (variable, méthode, classe) a clairement sémantique du nom. Avoir plus de commentaires que nécessaire le rend effectivement plus difficile (!) à lire le code, donc si votre collègue

• écrit des commentaires de documentation (Doxygen, JavaDoc, XML, commentaires, etc.) pour chaque classe, membre du type et de la méthode ET
• clairement les commentaires de toutes les parties du code qui ne sont pas auto-documentation ET
• écrit un commentaire pour chaque bloc de code qui explique l'intention, ou ce que fait le code sur un plus haut niveau d'abstraction (c'est à dire trouver tous les fichiers de plus de 10 MO au lieu de parcourir tous les fichiers dans un répertoire, de tester si la taille du fichier est de plus de 10 MO, le rendement de retour si vrai)

son code et de la documentation est très bien, à mon avis. Notez que l'auto-documenté code ne veut pas dire qu'il devrait y avoir pas de commentaires, mais seulement qu'il devrait y avoir pas de commentaires inutiles. La chose est, cependant, que par la lecture du code (y compris les observations et les commentaires de la documentation) devrait donner une compréhension immédiate de ce que fait le code et pourquoi. Si les "auto-documentation" code prend plus de temps pour comprendre que le code commenté, il n'est pas vraiment de l'auto-documentation.

Answer 3

Le code lui-même sera toujours l'explication la plus à jour de ce que fait votre code, mais à mon avis, il est très difficile d'expliquer l' intention , qui est l'aspect le plus vital des commentaires. Si c'est écrit correctement, nous savons déjà ce que le code fait, nous avons juste besoin de savoir pourquoi il le fait!

Answer 4

Quelqu'un a dit

1) N'écrivez des commentaires que pour du code difficile à comprendre.
2) Essayez de ne pas écrire du code difficile à comprendre.

Answer 5

L'idée derrière "l'auto-documentation" du code est que la logique du programme dans le code est trivialement suffisamment clairs pour l'expliquer à quelqu'un la lecture du code, non seulement ce que fait le code mais pourquoi il le fait.

À mon avis, l'idée de la véritable auto-documentation de code est un mythe. Le code peut vous dire la logique derrière ce qui se passe, mais il ne peut pas expliquer pourquoi il est fait d'une certaine façon, surtout si il ya plus d'une façon de résoudre un problème. Pour cette seule raison, il ne peut jamais remplacer bien commenté code.