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

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

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

À ce code auto-documentant, qui montre ce que est en cours:

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

Et puis à ce code documenté, ce qui explique mieux Pourquoi c'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 la version finale du code en tant que documentation avec zéro 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 voir clairement ce qu'est l'opération. Je préférerais le deuxième exemple auto-documenté à cela n'importe quel jour, 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 à jour de ce que fait votre code, mais à mon avis, il est très difficile pour lui d'expliquer intent, qui est l'aspect le plus vital des commentaires. Si c'est écrit correctement, nous savons déjà ce le code, nous avons juste besoin de savoir pourquoi, il le fait!

Quelqu'un a dit un jour

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-documentant" est que la logique du programme réel dans le code est assez trivialement claire pour expliquer à quiconque lit le code non seulement ce que le code fait 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'un moyen de résoudre un problème. Pour cette seule raison il ne peut jamais remplacer bien commenté code.

Je pense qu'il est pertinent de se demander si une ligne de code particulière est auto-documentée, mais à la fin 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. Prenez, 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 bien, mais ce qui suit est également 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 est plus approprié:

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

Dans 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 rouler 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 une excuse au lecteur. "Je suis désolé que mon code soit si opaque que vous ne pouvez pas le comprendre en le regardant". Nous devons juste accepter que nous ne sommes pas parfaits, mais nous nous efforçons d'être parfaits et de nous excuser quand nous en avons besoin.

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 variable.

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

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

Etc.

Après cela, vous vous retrouvez avec un code qui ne nécessite pas autant d'explications, il s'explique, vous devez donc supprimer les commentaires qui ne font que répéter les 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 contenues dans les autres.

Le code auto-documenté est une bonne pratique et s'il est fait correctement peut facilement transmettre le sens du code sans lire trop de commentaires. surtout dans les situations où le domaine est bien compris par tout le monde dans 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/aide.

Le code auto-documenté + les commentaires nécessaires aideront grandement les gens à travers les équipes.

Tout d'abord, il est bon d'entendre que le code de votre collègue est en fait plus clair que d'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 informé comprenne ce qu'il fait. Par exemple, ce morceau de code est auto-documenté:

print "Hello, World!"

Et ceci aussi:

factorial n = product [1..n]

Et ainsi est ce:

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)

Maintenant, cette idée d'un "lecteur informé" est très subjective et situationnelle. Si vous ou quelqu'un d'autre a du mal à suivre le code de votre collègue, alors 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-documentant.

Le meilleur argument que j'ai vu pour écrire du "Code Auto-documentant" est qu'il évite le problème du commentaire en texte libre non d'accord avec le code tel qu'il est écrit. La meilleure critique est que si le code peut décrire ce que et Comment Il fait par lui-même, il ne peut pas expliquer pourquoi quelque chose est fait d'une certaine manière.

Dans l'ordre:

• le code auto-documentant est un code qui exprime clairement son intention au lecteur.
• pas entièrement. Les commentaires sont toujours utiles pour commenter Pourquoi une stratégie particulière a été choisie. Cependant, les commentaires qui expliquent ce que fait une section de code indiquent un code insuffisamment auto-documenté et qui pourrait utiliser un refactoring..
• les commentaires mentent et deviennent obsolètes. Code dit toujours est plus susceptible de dire la vérité.
• Je n'ai jamais vu un cas où le quoi du code ne pouvait 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, que le code vraiment auto-documenté demande beaucoup d'auto-discipline et de discipline d'équipe. Vous devez apprendre à programmer plus déclarativement, et vous devez être très humble et éviter le code "intelligent" en faveur du code qui est si évident qu'il semble que n'importe qui aurait pu l'écrire.

Pour un, considérez l'extrait 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 par 3 lignes de code. Pire encore - les commentaires n'ajoutent rien que vous ne pouvez pas voir en lisant le code. Si vous avez 10 méthodes comme celle-ci, vous pouvez obtenir 'commentez la cécité' et ne pas remarquer la 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 la l'organisation globale est mieux expliquée dans un document distinct en dehors du code.

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

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

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

Juste mon pincée de sel...

Une chose que vous voudrez peut-être signaler à votre collègue est que, peu importe la façon dont son code est auto-documenté, si d'autres approches alternatives ont été envisagées et rejetées, cette information sera perdue à moins qu'il ne commente le code avec cette information. Parfois, il est tout aussi important de savoir qu'une alternative a été envisagée et pourquoi elle a été rejetée et que les commentaires de code sont les plus susceptibles de survivre au fil du temps.

Avez-vous entendu parler du projet "WEB" de Donald Knuth pour mettre en œuvre son concept de programmation alphabétisée? C'est plus qu'un code auto-documenté; c'est plus comme une documentation qui peut être compilée et exécutée en tant que code. Je ne sais pas combien il est utilisé aujourd'hui.

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 dans des cas particuliers (par exemple, se référer à un document d'algorithme spécifique). Qui devrait être auto-documenté.

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

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

Le point de vue que le code est auto-documenté me rend fou. Une ligne de code particulière ou un sous-algorithme peut être en effet auto-documenté, mais son but dans le plus grand picutre ne l'est tout simplement pas.

J'ai été tellement frustré par cela il y a un mois ou deux que j'ai écrit un article de blog entier décrivant mon point de vue. Poster ici.

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

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

J'ai eu un professeur qui croyait fermement à cette théorie En réalité, la meilleure chose que je me souviens de lui dire est " les commentaires sont pour poules mouillées"
Il nous a tous pris par surprise au début, mais il est logique.
Cependant, la situation est que même si vous pouvez être en mesure de comprendre ce qui se passe dans le code, mais quelqu'un qui a moins d'expérience que vous pouvez venir derrière vous et ne pas comprendre ce qui se passe. C'est à ce moment que les commentaires deviennent importants. Je sais souvent que nous ne pensons pas qu'ils soient importants, mais il y a très peu de cas où des commentaires sont inutiles.

Je suis surpris que personne n'ait apporté "programmation alphabétisée ", une technique développée en 1981 par Donald E. Knuth de TeX et" L'Art De La Programmation informatique " renommée.

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 à chacun la chose dont il a besoin - une description textuelle complète de l'intention du code, sans entrave par les exigences du langage de programmation, pour le lecteur humain et pur code pour le compilateur.

Les outils de programmation alphabétisés le font en vous donnant un balisage spécial pour un document qui indique aux outils quelle partie doit être source et quel est le texte. Le programme déchire plus tard les parties de code source du document et assemble un fichier de code.

J'ai trouvé un exemple sur le web d'il: 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 sur elle dans un bibliothèque (Donald E. Knuth, Lettré de la Programmation, de Stanford, en Californie: Centre pour l'Étude de la Langue et de l'Information, 1992, CSLI Notes de cours, pas de. 27.), vous devriez le lire.

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

Mon point de vue est écrit dans ce post:

Le seul conseil pour documenter votre code.

Extrait:

" au Lieu d'écrire beaucoup de commentaires pour expliquer les comportements subtils de votre programme, pourquoi ne pas restructurer votre logiques pour qu'elles soient évidentes? Au lieu de documenter quelle méthode est en train de faire, pourquoi ne pas choisir un nom clair pour cette méthode? Au lieu du marquage votre code pour indiquer le travail inachevé, pourquoi ne pas simplement jeter un NotImplementedException()? Plutôt se soucier de savoir si vos commentaires sonnent assez polis pour votre patron, votre collègues ou toute personne lisant le code, pourquoi ne pas simplement arrêter de s'inquiéter de ne pas les écrire du tout?

Plus votre code est clair, plus il est facile il s'agit de le maintenir, de l'étendre, de travailler dessus sur les éditions futures. Le moins ordorous est votre code, moins besoin il est de le commenter. Le plus les commentaires, le plus élevé de la coût de maintenance.

Je voudrais offrir une perspective de plus aux nombreuses réponses valides:

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 assemblage en cours d'exécution. Les langages de programmation sont à notre avantage. Nous ne voulons pas écrire de l'assemblée. Nous avons besoin de comprendre ce que l'on écrit. 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 ce n'est pas complètement réussi.

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

La plupart des langages de programmation ont une redondance pour que le compilateur puisse nous attraper quand nous ne sommes pas cohérents. D'autres langues utilisent plus d'inférence et essaient d'éliminer cela redondance.

Les noms de Type, les noms de méthode et les noms de variables 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 pour nous.

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 soit lisible pour nous. Si nous sommes bons en sémantique là où cela est permis et bons pour structurer le code, le code source devrait être facile à lisez 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 soustraire au problème, car au fil du temps, le code, les commentaires et la documentation divergent. Et c'est un facteur de discipline d'écrire du code clair (si vous êtes aussi strict sur vous - même).

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

• Code devrait être aussi facile et clair pour lire que possible.
• les commentaires doivent indiquer les raisons les décisions de conception que j'ai prises, comme: Pourquoi puis-je utiliser cet algorithme, ou limitations le code a, comme: fonctionnent pas lorsque ... (cela devrait être traité dans un contrat / assertion dans le code) (généralement dans la fonction / procédure).
• la Documentation devrait énumérer l'utilisation (appel converntions), côté effets, valeurs de retour possibles. Il peut être extrait du code en utilisant des outils comme jDoc ou xmlDoc. Il par conséquent est généralement en dehors de la fonction/procédure, mais à proximité de la le code qu'il décrit.

Cela signifie que les trois moyens de documenter le code vivent rapprochés 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 code soi-disant auto-documentant est qu'il transmet ce qu'il fait réellement. Alors que certains commentaires peuvent aider quelqu'un à mieux comprendre le code (par exemple, les étapes des algorithmes, etc.) c'est dans une certaine mesure redondant et je doute que vous convainquiez votre Pair.

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

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

Vous pouvez lui montrer un exemple de code qui semble bien, est évident, mais 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 commenter. 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. Il peut incomber au codeur de savoir s'il comblera le manque à gagner avec un commentaire ou renommer certaines variables et fonctions et refactorer le code.

Il ne peut pas vraiment remplacer votre documentation, car la documentation est ce que vous donnez à d'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/multiplie/etc lesdites valeurs... pour changer le programme, vous modifiez 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 ressemblant à des essais, expliquant les mathématiques, les conventions notationnelles que le code utilise et comment tout cela s'intègre. Nous parlons de centaines de lignes de documentation, ici.

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

Maintenant, bien sûr, ce genre de mesure extrême n'est pas nécessaire pour la plupart des cas. Je pense que la morale de l'histoire est: un code différent nécessite différentes quantités de documentation. Un 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 un sens, alors écrivez-LE aussi clairement que possible, puis utilisez autant de commentaires que nécessaire...

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

Good domain modeling 
+ good names (variabes, methods, classes) 
+ code examples (unit tests from use cases) 
= self documenting software 

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 toute modification du code pourrait être supprimée la prochaine fois que le projet est compilé
• une implémentation moins simple a été échangée contre un gain de performance (déroulement d'une boucle, création d'une table de recherche pour un calcul coûteux, etc.)

Il va être tout dans ce que l'équipe valorise dans sa documentation. Je suggère que documenter pourquoi / intention au lieu de comment est important et cela n'est pas toujours capturé dans le code auto-documenté. get / set non ceux - ci sont évidents-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:

Bissectionsearch

BinarySearch

BinaryChop

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

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

Il est généralement facile d'écrire du code qui AUTO-documente ce qu'il fait. Pour vous dire pourquoi il le fait, les commentaires sont plus approprié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. Vous ne pouvez pas dire tout le livre dans son titre, donc les abstractions principales 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é-chanceux vous et lui. Si vous pensez que vos collègues code a besoin de commentaires-il besoin. Ouvrez simplement l'endroit le plus non trivial, lisez-le une fois et voyez si vous avez tout compris ou non. Si le code est auto-documenté - alors vous devriez. Si ce n'est pas le cas - 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 intelligente comme 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 son code ne le fait pas expliquez - vous tout ce que vous devez comprendre - il a besoin de commentaires.