Qu'est-ce qu'un code auto-documenté et peut-il remplacer un code bien documenté? [fermé]

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.

À mon avis, tout code devrait être auto-documenté. Dans un bon code auto-documenté, vous n'avez pas à expliquer chaque ligne car chaque identifiant (variable, méthode, classe) a un nom sémantique clair . Avoir plus de commentaires que nécessaire rend en fait plus difficile (!) La lecture du code, donc si votre collègue

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

son code et sa documentation sont très bien, à mon avis. Notez que le code auto-documenté ne signifie pas qu'il ne devrait pas y avoir de commentaires, mais seulement qu'il ne devrait pas y avoir de commentaires inutiles. La chose est, cependant, qu'en lisant le code (y compris les commentaires et les commentaires de la documentation) devrait permettre de comprendre immédiatement ce que fait le code et pourquoi. Si le code "auto-documenté" est plus long à comprendre que le code commenté, il n'est pas vraiment auto-documenté.

Eh bien, puisqu'il s'agit de commentaires et de code, regardons du code réel. Comparez ce code typique:

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

À ce code auto-documenté, qui montre ce qui se fait:

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

Et puis à ce code documenté, qui explique mieux pourquoi cela se 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 la version finale du code en tant que documentation sans aucun commentaire nécessaire:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

Voici un exemple d'un mauvais style de commentaire:

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 commentaires sont utilisés lorsque les variables auraient dû être nommées de manière descriptive à la place, et les résultats d'une opération sont résumés lorsque nous pouvons clairement voir ce qu'est l'opération. Je préférerais le deuxième exemple auto-documenté à cela n'importe quand, et c'est peut-être ce dont parle votre ami quand il dit du code auto-documenté.

Je dirais que cela dépend du contexte de ce que vous faites. Pour moi, le code auto-documenté est probablement suffisant 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.

Le code lui-même sera toujours l'explication la plus récente 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. S'il est écrit correctement, nous savons déjà ce que fait le code, nous avons juste besoin de savoir pourquoi diable il le fait!

Quelqu'un a dit une fois

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

L'idée derrière le code "auto-documenté" est que la logique réelle du programme dans le code est assez claire pour expliquer à quiconque lit le code non seulement ce que fait le code mais pourquoi il le fait.

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

Je pense qu'il est pertinent de se demander si une ligne de code particulière est auto-documentée, mais au final, si vous ne comprenez pas la structure et la fonction d'une tranche de code, la plupart du temps, les commentaires ne vont pas aider. Prenons, par exemple, la tranche de code "correctement commenté" d'Amdfan:

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

Ce code est correct, mais ce qui suit est tout aussi informatif dans la plupart des systèmes logiciels modernes et reconnaît explicitement que l'utilisation d'un calcul newtonien est un choix qui peut être modifié si un autre paradigme physique était plus approprié:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

D'après mon expérience personnelle, il y a très peu de situations de codage "normales" où vous avez absolument besoin de commentaires. À quelle fréquence finissez-vous par lancer votre propre algorithme, par exemple? Fondamentalement, tout le reste est une question de structurer votre système afin qu'un codeur puisse comprendre les structures utilisées et les choix qui ont conduit le système à utiliser ces structures particulières.

J'oublie d'où je viens, mais:

Chaque commentaire dans un programme est comme des excuses au lecteur. "Je suis désolé que mon code soit si opaque que vous ne puissiez pas le comprendre en le regardant". Nous devons simplement accepter que nous ne sommes pas parfaits, mais nous nous efforçons d'être parfaits et continuer à nous excuser quand nous en avons besoin.

Tout d'abord, il est bon d'entendre que le code de votre collègue est en fait plus clair que les autres codes que vous avez vus. Cela signifie qu'il n'utilise probablement pas "l'auto-documentation" comme excuse pour être trop paresseux pour commenter son code.

Le code auto-documenté est un code qui ne nécessite pas de commentaires en texte libre pour qu'un lecteur averti comprenne ce qu'il fait. Par exemple, ce morceau de code est auto-documenté:

print "Hello, World!"

et c'est ainsi:

factorial n = product [1..n]

et c'est ainsi:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

Or, cette idée d'un "lecteur averti" est très subjective et situationnelle. Si vous ou quelqu'un d'autre a du mal à suivre le code de votre collègue, il ferait bien de réévaluer son idée d'un lecteur informé. Un certain niveau de familiarité avec la langue et les bibliothèques utilisées doit être supposé afin d'appeler le code auto-documenté.

Le meilleur argument que j'ai vu pour écrire du "code auto-documenté" est qu'il évite le problème des commentaires en texte libre qui ne sont pas en accord avec le code tel qu'il est écrit. La meilleure critique est que si le code peut décrire ce qu'il fait et comment il le fait par lui-même, il ne peut pas expliquer pourquoi quelque chose est fait d'une certaine manière.

Le code auto-documenté est un bon exemple de "SEC" (ne vous répétez pas). Ne dupliquez pas les informations dans les commentaires qui sont, ou peuvent être, dans le code lui-même.

Plutôt que d'expliquer à quoi sert une variable, renommez-la.

Plutôt que d'expliquer ce que fait un court extrait de code, extrayez-le dans une méthode et donnez-lui un nom descriptif (peut-être une version abrégée de votre texte de commentaire).

Plutôt que d'expliquer ce que fait un test compliqué, extrayez-le également dans une méthode et donnez-lui un bon nom.

Etc.

Après cela, vous vous retrouvez avec du code qui ne nécessite pas autant d'explications, il s'explique lui-même, vous devez donc supprimer les commentaires qui ne font que répéter des informations dans le code.

Cela ne signifie pas que vous n'avez aucun commentaire, il y a des informations que vous ne pouvez pas mettre dans le code, telles que des informations sur l'intention (le «pourquoi»). Dans le cas idéal, le code et les commentaires se complètent, chacun ajoutant une valeur explicative unique sans dupliquer les informations dans l'autre.

le code d'auto-documentation est une bonne pratique et s'il est fait correctement, il peut facilement transmettre la signification du code sans lire trop de commentaires. surtout dans les situations où le domaine est bien compris par tous les membres de l'équipe.

Cela dit, les commentaires peuvent être très utiles pour les nouveaux arrivants ou pour les testeurs ou pour générer des fichiers de documentation / d'aide.

le code d'auto-documentation + les commentaires nécessaires contribueront grandement à aider les gens au sein des équipes.

En ordre:

• Le code auto-documenté est un code qui exprime clairement son intention au lecteur.
• Pas entièrement. Les commentaires sont toujours utiles pour expliquer pourquoi une stratégie particulière a été choisie. Cependant, les commentaires qui expliquent ce que fait une section de code indiquent un code qui n'est pas suffisamment auto-documenté et pourrait utiliser une refactorisation.
• Les commentaires mentent et deviennent obsolètes. Le code dit toujours est plus susceptible de dire la vérité.
• Je n'ai jamais vu un cas où le quoi de code ne pourrait pas être suffisamment clair sans commentaires; cependant, comme je l'ai dit plus tôt, il est parfois nécessaire / utile d'inclure des commentaires sur le pourquoi .

Il est important de noter, cependant, qu'un code vraiment auto-documenté demande beaucoup de discipline personnelle et d'équipe. Vous devez apprendre à programmer de manière plus déclarative, et vous devez être très humble et éviter le code "intelligent" au profit d'un code si évident qu'il semble que n'importe qui aurait pu l'écrire.

Lorsque vous lisez un "code auto-documenté", vous voyez ce qu'il fait, mais vous ne pouvez pas toujours deviner pourquoi il le fait de cette manière particulière.

Il y a des tonnes de contraintes non liées à la programmation comme la logique métier, la sécurité, les demandes des utilisateurs, etc.

Lorsque vous effectuez la maintenance, ces informations de backgorund deviennent très importantes.

Juste ma pincée de sel ...

Tout d'abord, considérez l'extrait de code suivant:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Dans cet exemple, vous avez 5 lignes de commentaires pour 3 lignes de code. Pire encore - les commentaires n'ajoutent rien que vous ne puissiez voir en lisant le code. Si vous avez 10 méthodes comme celle-ci, vous pouvez obtenir la «cécité des commentaires» et ne pas remarquer la seule méthode qui s'écarte du modèle.

Si bien sûr, une meilleure version aurait été:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Pourtant, pour le code trivial, je préfère ne pas avoir de commentaires. L'intention et l'organisation globale sont mieux expliquées dans un document distinct en dehors du code.

La différence est entre "quoi" et "comment".

• Vous devez documenter "ce que" fait une routine.
• Vous ne devez pas documenter "comment" il le fait, sauf cas particulier (par exemple, référez-vous à un papier d'algorithme spécifique). Cela devrait être auto-documenté.

Une chose que vous voudrez peut-être signaler à votre collègue est que, quelle que soit l'auto-documentation de son code, si d'autres approches alternatives ont été envisagées et rejetées, ces informations seront perdues à moins qu'il ne commente le code avec ces informations. Parfois, il est tout aussi important de savoir qu'une alternative a été envisagée et pourquoi elle a été décidée et les commentaires de code sont les plus susceptibles de survivre dans le temps.

Dans une entreprise où je travaillais, l'un des programmeurs avait collé ce qui suit en haut de son moniteur.

"Documentez votre code comme la personne qui le maintient est un maniaque homicide qui sait où vous vivez."

le code auto-documenté utilise normalement des noms de variables qui correspondent exactement à ce que fait le code afin qu'il soit facile de comprendre ce qui se passe

Cependant, un tel "code auto-documenté" ne remplacera jamais les commentaires. Parfois, le code est tout simplement trop complexe et le code auto-documenté ne suffit pas, en particulier en termes de maintenabilité.

J'ai eu un jour un professeur qui croyait fermement à cette théorie. En fait, la meilleure chose que je me souvienne d'avoir dit est "Les commentaires sont pour les poules mouillées".
Cela nous a tous pris par surprise au début, mais cela a du sens.
Cependant, la situation est que même si vous pouvez comprendre ce qui se passe dans le code, mais quelqu'un qui est moins expérimenté que vous peut venir derrière vous et ne pas comprendre ce qui se passe. C'est à ce moment que les commentaires deviennent importants. Je sais à maintes reprises que nous ne pensons pas qu'elles sont importantes, mais il y a très peu de cas où les commentaires ne sont pas nécessaires.

Je suis surpris que personne n'ait provoqué la " programmation littéraire ", une technique développée en 1981 par Donald E. Knuth de TeX et la renommée de "The Art of Computer Programming".

La prémisse est simple: puisque le code doit être compris par un humain et que les commentaires sont simplement jetés par le compilateur, pourquoi ne pas donner à tout le monde tout ce dont ils ont besoin - une description textuelle complète de l'intention du code, sans entraves aux exigences du langage de programmation , pour le lecteur humain et du code pur pour le compilateur.

Les outils de programmation lettrée le font en vous offrant un balisage spécial pour un document qui indique aux outils quelle partie doit être source et ce qui est du texte. Plus tard, le programme extrait les parties de code source du document et assemble un fichier de code.

J'en ai trouvé un exemple sur le web: http://moonflare.com/code/select/select.nw ou la version HTML http://moonflare.com/code/select/select.html

Si vous pouvez trouver le livre de Knuth à ce sujet dans une bibliothèque (Donald E. Knuth, Literate Programming, Stanford, Californie: Center for the Study of Language and Information, 1992, CSLI Lecture Notes, n ° 27), vous devriez le lire.

C'est du code auto-documenté, complet avec le raisonnement et tout. Fait même un joli document, tout le reste est juste des commentaires bien écrits :-)

Je voudrais offrir une autre perspective aux nombreuses réponses valables:

Qu'est-ce que le code source? Qu'est-ce qu'un langage de programmation?

Les machines n'ont pas besoin de code source. Ils sont heureux de pouvoir assembler. Les langages de programmation sont à notre avantage. Nous ne voulons pas écrire d'assemblage. Nous devons comprendre ce que nous écrivons. La programmation consiste à écrire du code.

Devriez-vous être capable de lire ce que vous écrivez?

Le code source n'est pas écrit en langage humain. Il a été essayé (par exemple FORTRAN) mais il n'est pas complètement réussi.

Le code source ne peut pas avoir d'ambiguïté. C'est pourquoi nous devons y mettre plus de structure que nous ne le faisons avec le texte. Le texte ne fonctionne qu'avec le contexte, que nous tenons pour acquis lorsque nous utilisons du texte. Le contexte dans le code source est toujours explicité. Pensez à "utiliser" en C #.

La plupart des langages de programmation ont une redondance afin que le compilateur puisse nous rattraper lorsque nous ne sommes pas cohérents. D'autres langues utilisent plus d'inférence et tentent d'éliminer cette redondance.

Les noms de type, les noms de méthode et les noms de variable ne sont pas nécessaires aux ordinateurs. Ils sont utilisés par nous pour le référencement. Le compilateur ne comprend pas la sémantique, c'est à nous de l'utiliser.

Les langages de programmation sont un pont linguistique entre l'homme et la machine. Il doit être accessible en écriture pour nous et lisible pour eux. Les exigences secondaires sont qu'il doit être lisible pour nous. Si nous sommes bons en sémantique là où c'est permis et bons en structuration du code, le code source devrait être facile à lire même pour nous. Le meilleur code n'a pas besoin de commentaires.

Mais la complexité se cache dans chaque projet, vous devez toujours décider où mettre la complexité et quels chameaux avaler. Ce sont les endroits pour utiliser les commentaires.

Le code auto-documenté est un moyen facile de se retirer du problème, au fil du temps, le code, les commentaires et la documentation divergent. Et c'est un facteur de discipline pour écrire du code clair (si vous êtes si strict avec vous-même).

Pour moi, ce sont les règles que j'essaie de suivre:

• Le code doit être aussi facile et clair à lire que possible.
• Les commentaires doivent donner les raisons des décisions de conception que j'ai prises, comme: pourquoi utiliser cet algorithme, ou les limitations du code, comme: ne fonctionne pas quand ... (cela doit être traité dans un contrat / une assertion dans le code) (généralement dans la fonction / procédure).
• La documentation doit répertorier l'utilisation (appel de converntions), les effets secondaires, les valeurs de retour possibles. Il peut être extrait du code à l'aide d'outils comme jDoc ou xmlDoc. Il est donc généralement en dehors de la fonction / procédure, mais proche du code qu'il décrit.

Cela signifie que les trois moyens de documentation du code cohabitent étroitement et sont donc plus susceptibles d'être modifiés lorsque le code change, mais ne se chevauchent pas dans ce qu'ils expriment.

Le vrai problème avec le soi-disant code auto-documenté est qu'il transmet ce qu'il fait réellement. Bien que certains commentaires puissent aider quelqu'un à mieux comprendre le code (par exemple, les étapes des algorithmes, etc.), il est dans une certaine mesure redondant et je doute que vous convaincriez votre homologue.

Cependant, ce qui est vraiment important dans la documentation, c'est ce qui n'est pas directement évident dans le code: l'intention sous-jacente, les hypothèses, les impacts, les limitations, etc.

Être capable de déterminer qu'un code fait X d'un coup d'œil est beaucoup plus facile que de déterminer qu'un code ne fait pas Y. Il doit documenter Y ...

Vous pouvez lui montrer un exemple de code qui a l'air bien, qui est évident, mais qui ne couvre pas réellement toutes les bases de l'entrée, par exemple, et voir s'il le trouve.

Je pense que le code auto-documenté est un bon remplacement pour les commentaires. Si vous avez besoin de commentaires pour expliquer comment ou pourquoi le code est tel qu'il est, alors vous avez une fonction ou des noms de variables qui devraient être modifiés pour être plus explicatifs. Cela peut être dû au codeur de savoir s'il va combler le déficit avec un commentaire ou renommer certaines variables et fonctions et refactoriser le code.

Cela ne peut pas vraiment remplacer votre documentation, car la documentation est ce que vous donnez aux autres pour expliquer comment utiliser votre système, plutôt que comment il fait les choses.

Edit: je (et probablement tout le monde) devrait probablement avoir la disposition qu'une application de traitement du signal numérique (DSP) devrait être très bien commentée. C'est principalement parce que les applications DSP sont essentiellement 2 pour les boucles alimentées avec des tableaux de valeurs et ajoute / multiplient / etc lesdites valeurs ... pour changer le programme, vous changez les valeurs dans l'un des tableaux ... a besoin de quelques commentaires pour dire ce que vous faites dans ce cas;)

Lors de l'écriture de code mathématique, j'ai parfois trouvé utile d'écrire de longs commentaires de type essai, expliquant les mathématiques, les conventions de notation utilisées par le code et la manière dont tout s'emboîtait. Nous parlons ici de centaines de lignes de documentation.

J'essaie de rendre mon code aussi auto-documenté que possible, mais quand je reviens y travailler après quelques mois, j'ai vraiment besoin de lire l'explication pour ne pas en faire un hachage.

Maintenant, bien sûr, ce type de mesure extrême n'est pas nécessaire dans la plupart des cas. Je pense que la morale de l'histoire est la suivante: un code différent nécessite différentes quantités de documentation. Du code peut être écrit si clairement qu'il n'a pas besoin de commentaires - alors écrivez-le clairement et n'utilisez pas de commentaires là-bas!

Mais beaucoup de code a besoin de commentaires pour avoir du sens, alors écrivez-le aussi clairement que possible, puis utilisez autant de commentaires que nécessaire ...

Je dirais - comme beaucoup d'entre vous le font - que pour être vraiment auto-documenté, le code doit montrer une certaine forme d'intention. Mais je suis surpris que personne n'ait encore mentionné BDD - Behaviour Driven Development . Une partie de l'idée est que vous avez des tests automatisés (code) expliquant l'intention de votre code, qui est si difficile à rendre évident autrement.

Bonne modélisation de domaine 
+ bons noms (variabes, méthodes, classes) 
+ exemples de code (tests unitaires à partir de cas d'utilisation) 
= logiciel auto-documenté 

Quelques raisons pour lesquelles des commentaires supplémentaires en plus du code pourraient être plus clairs:

• Le code que vous regardez a été généré automatiquement et, par conséquent, toutes les modifications apportées au code peuvent être détruites la prochaine fois que le projet est compilé.
• Une implémentation moins que simple a été échangée contre un gain de performances (déroulement d'une boucle, création d'une table de recherche pour un calcul coûteux, etc.)

Ça va être tout ce que l'équipe apprécie dans sa documentation. Je suggérerais que documenter pourquoi / intention au lieu de comment est important et ce n'est pas toujours capturé dans le code d'auto-documentation. obtenir / définir non, cela est évident - mais le calcul, la récupération, etc. quelque chose du pourquoi devrait être exprimé.

Soyez également conscient de la différence dans votre équipe si vous venez de différentes nationalités. Les différences de diction peuvent apparaître dans la dénomination des méthodes:

BisectionSearch

Recherche binaire

BinaryChop

Ces trois méthodes apportées par des développeurs formés sur 3 continents différents font la même chose. Ce n'est qu'en lisant les commentaires décrivant l'algorithme que nous avons pu identifier la duplication dans notre bibliothèque.

Pour moi, lire du code qui a besoin de commentaires, c'est comme lire du texte dans une langue que je ne connais pas. Je vois une déclaration et je ne comprends pas ce qu'elle fait ni pourquoi - et je dois regarder les commentaires. J'ai lu une phrase et j'ai besoin de chercher dans le dictionnaire pour comprendre ce qu'elle signifie.

Il est généralement facile d'écrire du code qui auto-documente ce qu'il fait. Pour vous expliquer pourquoi, les commentaires sont plus adaptés, mais même ici, le code peut être meilleur. Si vous comprenez votre système à tous les niveaux d'abstraction, vous devriez essayer d'organiser votre code comme

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

Où le nom de la méthode reflète votre intention et le corps de la méthode explique comment vous atteignez votre objectif. De toute façon, vous ne pouvez pas dire le livre entier dans son titre, donc les principales abstractions de votre système doivent encore être documentées, ainsi que des algorithmes complexes, des contrats de méthode non triviaux et des artefacts.

Si le code que votre collègue produit est vraiment auto-documenté - vous et lui avez de la chance. Si vous pensez que le code de vos collègues a besoin de commentaires, il en a besoin. Ouvrez simplement l'endroit le plus banal, lisez-le une fois et voyez si vous avez tout compris ou non. Si le code est auto-documenté - alors vous devriez. Sinon - posez une question à votre collègue à ce sujet, après qu'il vous ait donné une réponse, demandez pourquoi cette réponse n'a pas été documentée dans les commentaires ou le code au préalable. Il peut prétendre que le code est auto-documenté pour une personne aussi intelligente que lui, mais il doit de toute façon respecter les autres membres de l'équipe - si vos tâches nécessitent la compréhension de son code et que son code ne vous explique pas tout ce que vous devez comprendre - il doit commentaires.

La plupart de la documentation / commentaires servent à aider les futurs développeurs / améliorateurs de code, ce qui rend le code maintenable. Plus souvent qu'autrement, nous finirions par revenir à notre module plus tard pour ajouter de nouvelles fonctionnalités ou optimiser. À ce moment-là, il serait plus facile de comprendre le code en lisant simplement les commentaires que de parcourir de nombreux points d'arrêt. De plus, je préfère passer du temps à penser à une nouvelle logique plutôt qu'à déchiffrer l'existant.

Je pense que ce qu'il pourrait vouloir dire, c'est que si les commentaires expliquent ce que fait le code, il devrait être réécrit pour être clair sur son intention. C'est ce qu'il entend par code auto-documenté. Souvent, cela peut signifier simplement diviser la fonction longue en morceaux logiques plus petits avec un nom de fonction descriptif.

Cela ne signifie pas que le code ne doit pas être commenté. Cela signifie que les commentaires doivent fournir une raison pour laquelle le code est écrit tel quel.

Je crois que vous devez toujours vous efforcer d'obtenir du code auto-documenté car cela facilite la lecture du code. Mais il faut aussi être pragmatique sur les choses.

Par exemple, j'ajoute généralement un commentaire à chaque membre de la classe (j'utilise des commentaires de documentation pour cela). Cela décrit ce que le membre est censé faire, mais pas comment il le fait. Je trouve que lorsque je lis le code, en particulier l'ancien code, cela m'aide à me rappeler rapidement à quoi sert le membre et je trouve aussi plus facile que de lire le code et de le travailler, surtout si le flux de code saute un peu .

C'est juste mon opinion. Je connais beaucoup de gens qui travaillent sans aucun commentaire et disent qu'ils trouvent que cela ne pose aucun problème. J'ai cependant demandé à quelqu'un une méthode qu'il avait écrite six mois auparavant et il a fallu réfléchir quelques minutes pour me dire exactement ce qu'il avait fait. Ce n'est pas un problème si la méthode est commentée.

Enfin, vous devez vous rappeler que les commentaires font également partie du système en tant que code. Lorsque vous refactorisez et modifiez les fonctionnalités, vous devez également mettre à jour vos commentaires. C'est un argument contre l'utilisation des commentaires car ils sont pires qu'inutiles s'ils sont incorrects.