Qu'est-ce qu'un code auto-documenté et peut-il remplacer un code bien documenté? IP Girl
Qu'est-ce qu'un code auto-documenté et peut-il remplacer un code bien documenté?
git certificate SSL – Chaîne de certificates invalide lors de l'access Comment remplacer correctement la méthode de clonage? Pour quelle raison choisirais-je un paramètre d'alignement de fichier du compilateur C # autre que 512? Méthode de mise en page définie, onDraw () non appelée Quelle est la différence entre PESSIMISTIC_READ et PESSIMISTIC_WRITE dans JPA? Peut-on dire que node.js est un serveur web? Comment connecter des commandes Cortana à des scripts personnalisés? Comment puis-je utiliser Fiddler pour modifier le code d'état dans une réponse HTTP? Pourquoi Math.Floor (Double) renvoie-t-il une valeur de type Double? Quand dois-je utiliser SynchronousQueue Quelle est la réponse appropriée du code d'état HTTP pour une requête générale infructueuse (pas une erreur)? Environment.TickCount vs DateTime.Now Appel d'une fonction à partir d'une chaîne avec le nom de la fonction dans Ruby Copier le contenu d'un répertoire dans un autre Meilleur moyen d'implémenter la limitation des requêtes dans ASP.NET MVC?
J'ai un collègue qui insiste sur le fait que son code n'a pas besoin de commentaires, c'est "l'auto-documentation".
J'ai revu son code et, bien qu'il soit plus clair que le code que j'ai vu d'autres produits, je ne suis toujours pas d'accord avec le fait que le code d'auto-documentation est aussi complet et utile que le code commenté et documenté.
Aidez-moi à comprendre son sharepoint vue.
Quel est le code d'auto-documentation
Peut-il remplacer le code bien commenté et documenté
Y a-t-il des situations où il vaut mieux que du code bien documenté et commenté
Existe-t-il des exemples où le code ne peut pas être auto-documenté sans commentaires
Ce n'est pas un argument – ne vous référez pas aux raisons pour lesquelles un code bien commenté et documenté est prioritaire – il y a beaucoup de ressources à ce sujet, mais elles ne sont pas convaincantes pour mes pairs. Je crois que je dois mieux comprendre sa perspective pour le convaincre du contraire. Commencez une nouvelle question si vous devez, mais ne discutez pas ici.
Wow, réponse rapide! S'il vous plaît lire toutes les réponses existantes et fournir des commentaires aux réponses plutôt que d'append de nouvelles réponses, sauf si votre réponse est vraiment différente de toutes les autres réponses ici.
En outre, ceux d'entre vous qui contestent l'auto-identification du code, c'est avant tout pour m'aider à comprendre la perspective (c'est-à-dire les aspects positifs) des évangélistes qui s'auto-documentent. Je m'attends à ce que les autres vous vident si vous ne restz pas sur le sujet.
Y a-t-il quelque chose comme la documentation officielle C?
À mon avis, tout code devrait être auto-documenté. En bon code auto-documenté, vous n'avez pas à expliquer chaque ligne car chaque identificateur (variable, méthode, classe) a un nom sémantique clair. Avoir plus de commentaires que nécessaire rend plus difficile (!) La lecture du code, donc si votre collègue
commente clairement toutes les parties du code qui ne sont pas auto-documentées ET
écrit un commentaire pour chaque bloc de code expliquant l'intention ou ce que le code fait à un niveau d'abstraction supérieur (par exemple, rechercher tous les fichiers de plus de 10 Mo au lieu de tous les fichiers d'un répertoire, tester si la taille du fichier est supérieure à 10 MB, rendement de retour si vrai )
son code et sa documentation vont bien, à mon avis. Notez que le code auto-documenté ne signifie pas qu'il ne devrait y avoir aucun commentaire, mais seulement qu'il ne devrait y avoir aucun commentaire inutile. Le fait est que, en lisant le code (y compris les commentaires et les commentaires sur la documentation), il faut comprendre immédiatement ce que fait le code et pourquoi. Si le code "d'auto-documentation" prend plus de temps à comprendre que le code commenté, il n'est pas vraiment auto-documenté.
Eh bien, comme il s'agit de commentaires et de code, regardons du code réel. Comparez ce code typique:
À ce code auto-documenté, qui montre ce qui se fait:
Et puis à ce code documenté, ce qui explique mieux pourquoi cela se fait:
Et la version finale du code en tant que documentation sans aucun commentaire nécessaire:
Voici un exemple de style de commentaire médiocre:
Dans le dernier exemple, les commentaires sont utilisés lorsque les variables doivent avoir été nommées de manière descriptive, et les résultats d'une opération sont résumés lorsque nous pouvons voir clairement quelle 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 lorsqu'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 (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 d'expliquer l' intention , qui est l'aspect le plus important des commentaires. Si c'est écrit correctement, nous soaps déjà ce que le code fait, nous avons juste besoin de savoir pourquoi il le fait sur terre !
Quelqu'un a dit une fois
1) N'écrivez que des commentaires pour un code difficile à comprendre.
L'idée derrière le code "auto-documenté" est que la logique du programme dans le code est assez 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 d'auto-documentation 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 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 le 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. Prenez, par exemple, la tranche d'amdfan de code "correctement commenté":
Ce code est correct, 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é:
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 lancer votre propre algorithme, par exemple? Fondamentalement, tout le rest consiste à structurer votre système pour 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 pour le lecteur. "Je suis désolé que mon code soit si opaque que vous ne pouvez pas le comprendre en le regardant". Nous devons simplement accepter que nous ne sums pas parfaits mais nous efforcer d'être parfaits et continuer à nous excuser quand nous en avons besoin.
Le code d'auto-documentation est un bon exemple de "DRY" (Don't Repeat Yourself). 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 que fait un extrait de code court, 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 aussi dans une méthode et donnez-lui un nom.
Après cela, vous vous retrouvez avec du code qui ne nécessite pas autant d'explications, explique-t-il, 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 existe certaines informations que vous ne pouvez pas inclure 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 correctement exécuté, peut facilement transmettre le sens du code sans lire trop de commentaires. en particulier 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 / aide.
le code d'auto-documentation + les commentaires nécessaires consortingbueront grandement à aider les membres des équipes.
Tout d'abord, il est bon d'entendre que le code de votre collègue est plus clair que tout autre code que vous avez vu. Cela signifie qu'il n'utilise probablement pas l'auto-documentation comme excuse pour être trop paresseux pour commenter son code.
Le code d'auto-documentation 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é:
Maintenant, cette idée de "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 pris en compte pour pouvoir appeler le code automatiquement.
Le meilleur argument que j'ai vu pour écrire du "code auto-documenté" est qu'il évite le problème du commentaire en texte libre qui ne correspond pas au code tel qu'il est écrit. La meilleure critique est que, même si le code peut décrire ce qu'il fait et comment il le fait, il ne peut pas expliquer pourquoi quelque chose est fait d'une certaine manière.
Le code d'auto-documentation 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 qu'une section de code fait sont indicatifs d'un code qui n'est pas suffisamment auto-documenté et qui pourrait utiliser un certain refactoring.
Les commentaires sont 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 du code ne pouvait pas être rendu 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 de l'auto-documentation nécessite beaucoup de discipline et de discipline. Vous devez apprendre à programmer de manière plus déclarative, et vous devez être très humble et éviter le code "intelligent" en faveur d'un code tellement évident qu'il semble que quelqu'un ait pu l'écrire.
Pour l'un, considérez l'extrait suivant:
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 un «commentaire aveugle» et ne pas remarquer la méthode qui s'écarte du modèle.
Bien sûr, une meilleure version aurait été:
Cependant, pour le code sortingvial, je préfère ne pas avoir de commentaires. L'intention et l'organisation globale sont mieux expliquées dans un document séparé du code.
Lorsque vous lisez un "code auto-documenté", vous voyez ce qu'il est en train de faire, mais vous ne pouvez pas toujours deviner pourquoi.
Il existe des tonnes de contraintes non liées à la programmation, telles que la logique métier, la sécurité, les demandes des utilisateurs, etc.
Lorsque vous faites de la maintenance, ces informations backgorund deviennent très importantes.
Juste ma pincée de sel …
Une chose que vous voudrez peut-être faire remarquer à votre collègue est que, même si son code est auto-documenté, si d'autres approches ont été envisagées et rejetées, ces informations seront perdues à moins de commenter le code avec ces informations. Parfois, il est tout aussi important de savoir qu'une alternative a été envisagée et pourquoi il a été décidé de ne pas le faire et que les commentaires de code sont les plus susceptibles de survivre avec le 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 devriez documenter "ce que" une routine fait.
Vous ne devez pas documenter "comment" il le fait, sauf cas particuliers (par exemple, se référer à un papier d'algorithme spécifique). Cela devrait être auto-documenté.
Dans une entreprise où je travaillais, l'un des programmeurs avait les éléments suivants sur le dessus de son moniteur.
"Documentez votre code comme la personne qui prétend que c'est un maniaque homocide qui sait où vous habitez."
Le sharepoint vue que le code est auto-documenté me rend fou. Une ligne de code particulière ou un sous-algorithme peut en effet s'auto-documenter, mais son but dans la grande image n'est tout simplement pas.
Il y a un mois ou deux, j'ai été tellement frustré par cela que j'ai écrit un article de blog complet décrivant mon sharepoint vue. Poster ici
le code d'auto-documentation utilise normalement des noms de variables qui correspondent exactement à ce que fait le code, de sorte qu'il est facile de comprendre ce qui se passe
Cependant, un tel "code auto-documenté" ne remplacera jamais les commentaires. Parfois, le code est trop complexe et le code auto-documenté ne suffit pas, notamment en termes de maintenabilité.
J'ai eu un jour un professeur qui croyait fermement en cette théorie. En fait, la meilleure chose que je me souvienne de lui 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 êtes en mesure de comprendre ce qui se passe dans le code, une personne moins expérimentée peut vous accompagner et ne pas comprendre ce qui se passe. C'est à ce moment que les commentaires deviennent importants. Je sais à plusieurs resockets que nous ne pensons pas qu'ils sont importants, mais il y a très peu de cas où les commentaires sont inutiles.
Je suis surpris que personne n'ait créé " Literate Programming ", une technique développée en 1981 par Donald E. Knuth de TeX et "The Art of Computer Programming".
La prémisse est simple: puisque le code doit être compris par un humain et que le compilateur jette simplement les commentaires, pourquoi ne pas donner à chacun ce dont il a besoin – une description textuelle complète de l'intention du code, libre de toute exigence de langage de programmation , pour le lecteur humain et le code pur pour le compilateur.
Les outils de programmation littérale font cela en vous donnant un balisage spécial pour un document qui indique aux outils quelle partie doit être la source et quel est le texte. Le programme extrait ensuite les parties du code source du document et assemble un fichier de code.
J'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, Programmation Littéraire, Stanford, Californie: Centre d'étude du langage et de l'information, 1992, CSLI Notes de lecture, n ° 27), vous devriez le lire.
C'est du code auto-documenté, complet avec le raisonnement et tout. Même fait un beau document, tout le rest n'est que des commentaires bien écrits 🙂
Mon avis est écrit dans ce post:
Au lieu d'écrire beaucoup de commentaires pour expliquer les comportements subtils de votre programme, pourquoi ne pas restructurer vos logiques pour qu'elles deviennent évidentes? Au lieu de documenter ce que fait une méthode, pourquoi ne pas choisir un nom clair pour cette méthode? Au lieu de baliser votre code pour indiquer un travail inachevé, pourquoi ne pas simplement lancer une exception NotImplementedException ()? Au lieu de vous inquiéter de la politesse de vos commentaires envers votre patron, vos collègues ou toute personne lisant le code, pourquoi ne pas cesser de vous inquiéter en ne les écrivant pas du tout?
Plus votre code est clair, plus il est facile de le gérer, de l'étendre, de travailler sur les futures éditions. Le moins ordinal est votre code, moins il y a besoin de le commenter. Plus les commentaires sont élevés, plus le coût de maintenance est élevé.
Je voudrais offrir une autre perspective aux nombreuses réponses valables:
Quel est le code source? Qu'est-ce qu'un langage de programmation?
Les machines n'ont pas besoin de code source. Ils sont heureux d'assemblage en cours. Les langages de programmation sont à notre avantage. Nous ne voulons pas écrire d'assemblage. Nous devons comprendre ce que nous écrivons. La programmation concerne l'écriture de code.
Devez-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'a pas complètement réussi.
Le code source ne peut avoir d'ambiguïté. C'est pourquoi nous devons y mettre plus de structure qu'avec du texte. Le texte ne fonctionne qu'avec le contexte, ce que nous prenons pour acquis lorsque nous utilisons du texte. Le contexte dans le code source est toujours explicite. Pensez à "utiliser" en C #.
La plupart des langages de programmation ont une redondance afin que le compilateur puisse nous attraper lorsque nous ne sums 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 d'utiliser.
Les langages de programmation constituent un pont linguistique entre l'homme et la machine. Il doit être accessible en écriture pour nous et lisible pour eux. Les demandes secondaires sont que cela devrait nous être lisible. Si nous sums bons en sémantique lorsque cela est autorisé et que nous sums bons pour structurer le code, le code source doit ê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 d'auto-documentation est un moyen facile de se soustraire au problème, ce qui, avec le code temporel, les commentaires et la documentation, divergent. Et écrire un code clair est un facteur de discipline (si vous êtes si ssortingct sur vous-même).
Pour moi, ce sont les règles que j'essaye de suivre:
Le code doit être aussi facile et clair à lire que possible.
Les commentaires devraient donner des raisons aux décisions de conception que j'ai sockets, comme: pourquoi est-ce que j'utilise cet algorithme, ou les limitations du code, comme: ne fonctionne pas quand … (ceci doit être traité dans un contrat / assertion dans le code) dans la fonction / procédure).
La documentation doit répertorier les utilisations (convocation des appels), les effets secondaires, les valeurs de retour possibles. Il peut être extrait du code en utilisant des outils tels que jDoc ou xmlDoc. Il est donc généralement hors de la fonction / procédure, mais proche du code qu'il décrit.
Cela signifie que les trois moyens de documentation du code sont proches les uns des autres 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 d'auto-documentation 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 puissiez convaincre votre pair.
Cependant, ce qui est vraiment important dans la documentation, ce sont les éléments qui ne ressortent pas directement du code: intention sous-jacente, hypothèses, impacts, limitations, etc.
Être capable de déterminer qu'un code X d'un coup d'œil est plus facile que de pouvoir déterminer qu'un code ne fait pas Y. Il doit documenter Y …
Vous pourriez lui montrer un exemple de code qui a l'air bien, qui est évident, mais qui ne couvre pas toutes les bases de l'entrée, par exemple, et voir s'il le trouve.
Je pense que le code d'auto-documentation est un bon substitut 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 doivent être modifiés pour être plus explicatifs. Le codeur peut décider s'il comblera le manque à gagner avec un commentaire ou renommera certaines variables et fonctions et refactorisera le code.
Cela ne peut pas vraiment remplacer votre documentation, car la documentation est ce que vous donnez aux autres pour leur expliquer comment utiliser votre système, plutôt que comment il fait les choses.
Edit: Je (et probablement tout le monde) devrait probablement prévoir qu'une application DSP (Digital Signal Processing) soit 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 dit les valeurs … pour changer le programme, vous changez les valeurs dans l'un des tableaux … nécessite quelques commentaires pour dire quoi vous faites dans ce cas;)
The code you're looking at was generated automatically, and hence any edits to the code might be clobbered the next time the project is comstackd
Its going to be all in what the team values in its documentation. I would suggest that documenting why/intent instead of how is important and this isn't always captured in self documenting code. get/set no these are obvious – but calculation, resortingeval etc something of the why should be expressed.
These three methods consortingbuted from developers trained on 3 different continents do the same thing. Only by reading the comments that described the algorithm were we able to identify the duplication in our library.
Where method name reflects your intent and method body explains how you achieve your goal. You anyway can not tell entire book in its title, so main abstractions of your system still have to be documented, as well as complex algorithms, non-sortingvial method contracts and artifacts.
If the code that your colleague produc is really self-documented – lucky you and him. If you think that your colleagues code needs comments – it needs. Just open the most non-sortingvial place in it, read it once and see if you understood everything or not. If the code is self-documented – then you should. If not – ask your colleague a question about it, after he gives you an answer ask why that answer was not documented in comments or code beforehand. He can claim that code is self-document for such smart person as him, but he anyway has to respect other team members – if your tasks require understanding of his code and his code does not explain to you everything you need to understand – it needs comments.