J'ai un collègue qui insiste sur le fait que son code n'a pas besoin de commentaires, c'est "auto-documentation".
J'ai examiné son code, et bien qu'il soit plus clair que le code que j'ai vu d'autres produire, je ne suis toujours pas d'accord pour dire que le code auto-documenté est aussi complet et utile que le code commenté et documenté.
Aidez-moi à comprendre son point de vue.
- Qu'est-ce que le code auto-documenté
- Peut-il vraiment remplacer un code bien commenté et documenté
- Y a-t-il des situations où c'est mieux qu'un code bien documenté et commenté
- Existe-t-il des exemples où le code ne peut pas être auto-documenté sans commentaires
C'est peut-être juste mes propres limites, mais je ne vois pas comment cela peut être une bonne pratique.
Ce n'est pas censé être un argument - veuillez ne pas mentionner les raisons pour lesquelles un code bien commenté et documenté est une priorité élevée - il existe de nombreuses ressources le montrant, mais elles ne sont pas convaincantes pour mon homologue. Je crois que je dois mieux comprendre son point de vue pour le convaincre du contraire. Commencez une nouvelle question si vous devez, mais ne discutez pas ici.
Wow, réponse rapide! Veuillez lire toutes les réponses existantes et fournir des commentaires sur les réponses plutôt que d'ajouter de nouvelles réponses, à moins que votre réponse ne soit vraiment différente de toutes les autres réponses ici.
De plus, ceux d'entre vous qui plaident contre le code auto-documenté - c'est principalement pour m'aider à comprendre la perspective (c'est-à-dire les aspects positifs) des évangélistes du code auto-documenté. J'espère que d'autres vous dévalueront si vous ne restez pas sur le sujet.
i++; // increment i
- mais sans explication sur la raison pour laquellei
il faudrait incrémenter à ce stade de la fonction.