Qu'est-ce qu'un code auto-documenté et peut-il remplacer un code bien documenté?
J'ai un collègue qui insiste sur le fait que son code n'a pas besoin de commentaires, c'est "auto-documenté".
J'ai examiné son code et, bien que ce soit plus clair que le code que j'ai vu produire par d'autres, je ne suis toujours pas d'accord sur le fait qu'un code auto-documenté est aussi complet et utile qu'un code commenté et documenté.
Aidez-moi à comprendre son point de vue.
- Quel est le code auto-documentant
- Peut-il vraiment remplacer un 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 éventuellement pas s'auto-documenter sans commentaires
Peut-être que ce sont juste mes propres limites, mais je ne vois pas en quoi cela peut être une bonne pratique.
Ceci n'est pas censé être un argument - veuillez ne pas donner les raisons pour lesquelles un code bien commenté et documenté est une priorité élevée - de nombreuses ressources le montrent, mais elles ne sont pas convaincantes pour mon pair. 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 commenter 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.
En outre, ceux d'entre vous qui plaident contre le code auto-documentant - ceci est principalement pour m'aider à comprendre le point de vue (aspects positifs) des évangélistes du code auto-documenté. Je m'attends à ce que les autres vous réservent une voix si vous ne restez pas sur le sujet.
À mon avis, tout code devrait être auto-documenté. Dans un bon code auto-documenté, il n'est pas nécessaire d'expliquer chaque ligne car chaque identificateur (variable, méthode, classe) a une sémantique claire prénom. Avoir plus de commentaires que nécessaire rend en réalité 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 sont non auto-documentées ET
- écrit pour chaque bloc de code un commentaire expliquant l'intention ou l'action du code à un niveau d'abstraction supérieur (c.-à-d. trouve tous les fichiers de plus de 10 Mo au lieu de parcourir tous les fichiers d'un répertoire, testez si la taille du fichier est supérieure à 10 Mo, donnez le retour si vrai )
son code et sa documentation sont bien, à mon avis. Notez que le code auto-documenté signifie pas qu'il ne doit y avoir aucun commentaire, mais seulement qu'il ne doit pas y avoir de commentaire inutile. Le problème, cependant, est qu’en lisant le code (y compris les commentaires et les commentaires de documentation), on doit immédiatement comprendre ce qu’il fait et pourquoi. Si le code "auto-documenté" prend plus de temps à comprendre que le code commenté, ce n'est pas vraiment auto-documenté.
Eh bien, puisqu'il s'agit de commentaires et de code, examinons un code réel. Comparez ce code typique:
float a, b, c; a=9.81; b=5; c= .5*a*(b^2);
A ce code auto-documenté, qui montre quoi est en cours de réalisation:
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
Et ensuite à 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 de code en tant que documentation avec zéro commentaire requis:
float computeDisplacement(float timeInSeconds) {
const float gravitationalForce = 9.81;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
return displacement;
}
Voici un exemple de style de commentaire médiocre:
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 plutôt dû être nommées de manière descriptive, et les résultats d'une opération sont résumés lorsque nous pouvons voir clairement en quoi consiste l'opération. Je préférerais le deuxième exemple auto-documenté à ce jour-là, et c'est peut-être ce dont parle votre ami lorsqu'il parle de 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 à la base de ce qui est derrière (dans cet exemple, l'équation) est également utile.
Le code lui-même constituera toujours l'explication la plus récente de ce que fait votre code, mais à mon avis, il est très difficile pour lui d'expliquer l'intention, qui est l'aspect le plus important des commentaires. . Si c'est écrit correctement, nous savons déjà quoi le code le fait, nous avons juste besoin de savoir pourquoi sur terre 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 du code difficile à comprendre.
L'idée derrière le code "auto-documenté" est que la logique du programme dans le code est suffisamment claire pour expliquer à quiconque le lit le code, non seulement ce qu'il fait, mais aussi 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 c'est fait d'une certaine manière, surtout 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 vous seront d'aucun secours. 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 convient, mais les informations suivantes sont tout aussi informatives dans la plupart des systèmes logiciels modernes et reconnaissent 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 existe très peu de situations de codage "normales" dans lesquelles vous avez absolument besoin de commentaires. À quelle fréquence finissez-vous par lancer votre propre algorithme, par exemple? Fondamentalement, tout le reste consiste à structurer votre système afin qu'un codeur puisse comprendre les structures en cours d'utilisation 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 puissiez pas le comprendre en le regardant". Nous devons simplement accepter le fait que nous ne sommes pas parfaits mais nous efforçons de l'être et de nous excuser dès que nous en avons besoin.
Le code auto-documenté est un bon exemple de "DRY" (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 attribuez-lui un nom descriptif (peut-être une version abrégée du texte de votre 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 un code qui nécessite moins d’explications, il s’explique, 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 insérer 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 l'information de l'autre.
le code auto-documenté est une bonne pratique et, si cela est fait correctement, peut facilement en expliquer le sens 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 venus ou les testeurs ou pour générer des fichiers de documentation/aide.
un code auto-documenté + les commentaires nécessaires contribueront grandement à aider les membres des équipes.
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 n'exige pas de commentaires en texte libre pour qu'un lecteur averti puisse comprendre ce qu'il fait. Par exemple, ce morceau de code est auto-documenté:
print "Hello, World!"
et c'est la même chose:
factorial n = product [1..n]
et c'est la même chose:
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 de "lecteur averti" est très subjective et situationnelle. Si vous ou quelqu'un d'autre avez des difficultés à suivre le code de votre collègue, il ferait bien de réévaluer son idée de lecteur averti. Un certain niveau de connaissance du langage et des bibliothèques utilisés doit être supposé pour appeler un code auto-documenté.
Le meilleur argument que j'ai vu pour l'écriture de "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, bien que le code puisse décrire quoi et comment il le fait tout seul, il ne peut pas expliquer pourquoi quelque chose se fait d'une certaine manière .
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 commenter pourquoi une stratégie particulière a été choisie. Cependant, les commentaires qui expliquent quoi une section de code est en train d'indiquer un code insuffisamment auto-documenté et qui pourrait nécessiter une refactorisation.
- Les commentaires mentent et deviennent obsolètes. Code
raconte toujoursest plus susceptible de dire la vérité. - Je n'ai jamais vu un cas où le quoi du 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 un commentaire sur le pourquoi.
Cependant, il est important de noter que le code réellement auto-documenté nécessite 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.
D'une part, 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 sur 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 méthode qui s'écarte du modèle.
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 séparé 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 le fait de cette manière.
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 effectuez la maintenance, ces informations en amont deviennent très importantes.
Juste ma pincée de sel ...
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 dans des cas particuliers (par exemple, reportez-vous à un algorithme spécifique). Cela devrait être auto-documenté.
Avez-vous entendu parler du projet "WEB" de Donald Knuth visant à mettre en œuvre son concept littératie programmée ? C'est plus qu'un code auto-documenté; cela ressemble plus à de la documentation qui peut être compilée et exécutée sous forme de code. Je ne sais pas combien il est utilisé aujourd'hui cependant.
Dans une entreprise où je travaillais, l'un des programmeurs avait ce qui suit collé au sommet de son moniteur.
"Documentez votre code comme si la personne qui la maintient est un maniaque homocide qui sait où vous habitez."
Vous voudrez peut-être faire remarquer à votre collègue que, peu importe l’autodétermination de son code, si d’autres méthodes étaient envisagées et rejetées, cette information serait perdue à moins qu’il ne commente le code avec cette information. Parfois, il est tout aussi important de savoir qu’une solution de rechange a été envisagée et pourquoi elle a été décidée et les commentaires de code ont toutes les chances de survivre avec le temps.
Je suis surpris de constater que personne n'a apporté " Literate Programming ", une technique développée en 1981 par Donald E. Knuth de TeX et "The Art of Computer Programming".
Le principe est simple: puisque le code doit être compris par un humain et que le compilateur jette tout commentaire, pourquoi ne pas donner à tout le monde ce dont il a besoin - une description textuelle complète de l'intention du code, sans aucune restriction quant aux exigences du langage de programmation , pour le lecteur humain et du code pur pour le compilateur.
Pour ce faire, les outils de programmation alphabétiques vous fournissent une annotation spéciale pour un document indiquant aux outils quelle partie doit être la source et quel est le texte. Le programme extrait ensuite les parties de 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, Literate Programming, Stanford, Californie: Centre d'étude de la langue et de l'information, 1992, Notes de conférence CSLI, n ° 27.), vous devriez le lire.
C'est un code auto-documenté, complet avec le raisonnement et tout. Même fait un beau document, tout le reste est juste des commentaires bien écrits :-)
Le point de vue selon lequel le code est auto-documenté me rend fou. Une ligne de code particulière ou un sous-algorithme peut être auto-documenté, mais son objectif dans la grande image ne l’est tout simplement pas.
Cela m'a tellement frustré il y a un mois ou deux que j'ai écrit un article de blog entier décrivant mon point de vue. poste ici .
Mon point de vue est écrit dans ce post:
Le seul conseil pour documenter votre code.
Extrait:
Au lieu de rédiger de nombreux commentaires pour expliquer les comportements subtils de votre programme, pourquoi ne pas restructurer vos logiques pour les rendre é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 marquer votre code pour indiquer le travail non terminé, pourquoi ne pas simplement lancer une NotImplementedException ()? Au lieu de vous inquiéter de savoir si vos commentaires paraissent assez polis à votre patron, à vos collègues ou à quiconque lit le code, pourquoi ne pas arrêter de vous inquiéter en ne les écrivant pas du tout?
Plus votre code est clair, plus il est facile à gérer, à étendre, à travailler sur de futures éditions. Moins votre code est ordonné, moins il est nécessaire de le commenter. Plus les commentaires sont nombreux, 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 de diriger l'Assemblée. Les langages de programmation sont à notre avantage. Nous ne voulons pas écrire Assembly. Nous devons comprendre ce que nous écrivons. La programmation consiste à écrire du code.
Devez-vous être capable de lire ce que vous écrivez?
Le code source n'est pas écrit en langage humain. Cela a été essayé (par exemple, FORTRAN) mais cela n’a pas complètement abouti.
Le code source ne peut pas 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 quand nous ne sommes pas cohérents. D'autres langues utilisent plus d'inférence et tentent d'éliminer cette redondance.
Les noms de types, les noms de méthodes 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 à nous d'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 soit lisible par nous. Si nous sommes bons en sémantique là où cela est autorisé et en structurant le 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ù placer la complexité et quels chameaux avaler. Ce sont les endroits pour utiliser les commentaires.
le code auto-documenté utilise normalement des noms de variables qui correspondent exactement à ce qu'il est en train de faire pour qu'il soit facile de comprendre ce qui se passe.
Toutefois, un tel "code auto-documenté" 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 jour un professeur qui était un fervent partisan de cette théorie. En fait, la meilleure chose que je me souvienne de lui avoir dite est "Les commentaires sont pour les poules mouillées"
Cela nous a tous surpris au début, mais cela a du sens.
Cependant, la situation est la suivante: même si vous êtes capable de comprendre ce qui se passe dans le code, une personne moins expérimentée que vous risquez de vous suivre et de ne pas comprendre ce qui se passe. C'est à ce moment que les commentaires deviennent importants. Je sais souvent que nous ne pensons pas que ce soit important, mais il y a très peu de cas où les commentaires sont inutiles.
Lors de la rédaction d'un code mathématique, j'ai parfois trouvé utile de rédiger de longs commentaires ressemblant à des essais, expliquant le calcul, les conventions de notation utilisées par le code et la manière dont tout cela s'emboîtait. Nous parlons ici de centaines de lignes de documentation.
J'essaie de rendre mon code aussi auto-documenté que possible, mais lorsque je reviens au travail après quelques mois, j'ai vraiment besoin de lire l'explication pour ne pas en faire un hash.
Bien entendu, 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. Certains codes peuvent être écrits si clairement qu'ils ne nécessitent pas de commentaires - écrivez-les aussi clairement et n'utilisez pas de commentaires ici!
Mais beaucoup de code a besoin de commentaires pour que cela ait un sens, alors écrivez-le le plus clairement possible, puis utilisez autant de commentaires que nécessaire ...
Je pense que le code auto-documenté remplace bien les commentaires. Si vous avez besoin de commentaires pour expliquer comment ou pourquoi le code est tel qu'il est, vous devez alors modifier les noms de fonction ou de variable pour qu'ils soient plus explicatifs. C’est peut-être au codeur de décider s’il va combler le manque à gagner avec un commentaire ou renommer certaines variables et fonctions ainsi que le code de refactoring.
Il ne peut toutefois pas remplacer votre documentation, car elle est ce que vous donnez à d’autres pour expliquer comment utiliser votre système et non comment il fonctionne.
Edit: Je (et probablement tous les autres) devrais probablement avoir la disposition selon laquelle 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 les valeurs dites ... pour changer le programme vous changez les valeurs dans l'un des tableaux ... besoin de quelques commentaires pour dire quoi vous faites dans ce cas;)
Le code auto-documenté est un moyen facile de résoudre le problème, car le code temporel, les commentaires et la documentation divergent. Et écrire un code clair est un facteur de discipline (si vous êtes aussi strict que 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, telles que: pourquoi utiliser cet algorithme, ou les limitations du code, telles que: ne fonctionne pas quand ... (ceci doit être traité dans un contrat/assertion dans le code) (généralement dans la fonction/procédure).
- La documentation doit répertorier les utilisations (convocations d’appel), les effets secondaires et les valeurs de retour possibles. Il peut être extrait du code à l'aide d'outils tels que jDoc ou xmlDoc. C'est donc généralement en dehors de la fonction/procédure, mais proche du code qu'elle décrit.
Cela signifie que les trois méthodes de documentation du code sont proches l'une de l'autre et sont donc plus susceptibles d'être modifiées lorsque le code est modifié, mais ne se chevauchent pas dans ce qu'elles expriment.
Le vrai problème avec ce que l'on appelle le 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 (étapes de l'algorithme, etc.), il est dans une certaine mesure redondant et je doute que vous convainciez votre pair.
Cependant, ce qui est vraiment important dans la documentation, ce sont des éléments qui ne ressortent pas directement du code: intention sous-jacente, hypothèses, impacts, limites, etc.
Il est beaucoup plus facile de déterminer qu'un code fait X d'un coup d'œil 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 a l'air bien, qui est évident, mais ne couvre pas toutes les bases de l'entrée, par exemple, et voir s'il le trouve.
Je dirais, comme beaucoup d’entre vous, que pour être véritablement documenté, le code doit montrer une forme d’intention. Mais je suis surpris que personne n'ait encore mentionné BDD - Développement basé sur le comportement . Une partie de l’idée est que vous disposiez de tests automatisés (code) expliquant l’intention de votre code, ce qui est si difficile à rendre évident autrement.
Modélisation de bon domaine + Bons noms (variables, méthodes, classes) + Exemples de code (tests unitaires à partir de cas d'utilisation) = Logiciel auto-documentant
Quelques raisons pour lesquelles des commentaires supplémentaires en plus du code peuvent être plus clairs:
- Le code que vous consultez a été généré automatiquement. Par conséquent, il est possible que les modifications apportées au code soient annulées lors de la prochaine compilation du projet.
- Une implémentation moins que simple a été échangé pour un gain de performance (déroulement d'une boucle, création d'une table de recherche pour un calcul coûteux, etc.)
Cela va être tout ce que l'équipe valorise dans sa documentation. Je suggérerais que documenter pourquoi/intention plutôt que comment soit important et que cela ne soit pas toujours consigné dans un code auto-documenté. get/set no ce sont des notions évidentes - mais le calcul, la récupération, etc.
Sachez également que votre équipe est différente si vous venez de différentes nationalités. Les différences de diction peuvent se traduire par la dénomination de 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.
// si ce n'est pas grave, ne vous inquiétez pas.
// Si vous écrivez des commentaires partout, les plus importants ne seront pas vus
- Méthode Commentaires sur le paramètre: Must die. C'est la duplication de code.
// Les paramètres doivent être explicites.
- Facteur WTF: Quelqu'un, y compris moi-même, dira-t-il WTF?
La plupart des documents/commentaires servent à aider les futurs développeurs/développeurs de code, rendant ainsi le code maintenable. Le plus souvent, nous reviendrions plus tard dans notre module pour ajouter de nouvelles fonctionnalités ou optimiser. À ce moment-là, il serait plus facile de comprendre le code en lisant simplement les commentaires qu'en parcourant de nombreux points d'arrêt. En outre, je préférerais passer du temps à réfléchir à une nouvelle logique plutôt qu’à déchiffrer l’existant.
Pour moi, lire du code qui a besoin de commentaires revient à lire un texte dans une langue que je ne connais pas. Je vois une déclaration et je ne comprends pas ce qu’elle fait ou pourquoi - et je dois regarder les commentaires. J'ai lu une phrase et j'ai besoin de regarder dans le 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, les commentaires sont plus appropriés, mais même dans ce cas, 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ù nom de 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 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 le code de vos collègues a besoin de commentaires, il en a besoin. Ouvrez simplement l'endroit le plus simple, 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. Après réponse, demandez-lui pourquoi cette réponse n'était pas documentée à l'avance dans les commentaires ou dans le code. Il peut prétendre que le code est un document personnel 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 une compréhension de son code et que ce dernier ne vous explique pas tout ce que vous devez comprendre, il doit commentaires.
Une bonne structure de conception permet de souligner que certaines fonctions sont destinées à un usage général et d'autres à une logique de gestion aléatoire, même si vous n'avez pas de commentaire disant "cette fonction est générale".
Nous ne devons cependant pas oublier la documentation de conception et de spécification. Ceux qui ont ou du moins devraient avoir la plupart des textes qui ne sont pas nécessairement nécessaires dans les commentaires. Les logiciels ont souvent aussi des manuels d’utilisation et d’autres documents de description, qui doivent être synchronisés avec ce que fait le programme. La situation n’est pas géniale si l’utilisateur doit découvrir ce que le logiciel fait à partir du code source au lieu d’un manuel. Donc, le code auto-documenté ne signifie toujours pas que le logiciel réel a été documenté.
Pensez également à la traçabilité des fonctionnalités. Lorsque vous avez votre manuel, vous devriez être en mesure de retracer les fonctionnalités jusqu'au code source et inversement pour une meilleure maintenance. Les manuels et les spécifications ne concernent pas vraiment la programmation, mais le génie logiciel. Plus le logiciel est volumineux, plus l'ingénierie est nécessaire.
Si votre code n'est pas complètement clair sans commentaires, vous pouvez améliorer votre code.
Je ne dis pas "ne commentez pas le code pas clair". Je dis "rend ton code clair".
Si vous finissez par laisser votre code peu clair d'une manière ou d'une autre, alors utilisez les commentaires pour compenser.
Quelques perspectives du camp non commentant.
Le code (commenté) "bien commenté" est plus difficile à lire et à comprendre. D'une part, il y a tout simplement plus de texte à numériser. Cela augmente l'effort cognitif dans la compréhension d'une base de code - le texte non fonctionnel prend de la place sur l'écran qui pourrait être utilisé pour afficher le code.
Un autre gros problème avec les commentaires est qu’ils ne sont pas fiables - en particulier sur les anciennes bases de code, la pourriture des commentaires s’effectue plus rapidement que la pourriture des bits.
Et bien sûr, il y a l'effort impliqué dans la rédaction des commentaires. À l'exception du clarificateur occasionnel à une ligne, chaque fois que je commence à commenter du code, je ressens l'un des deux sentiments coupables.
- cette information doit aller dans la documentation de soutien globale
- J'ai besoin de nettoyer mon code
Je pense qu'il pourrait en venir au fait que si les commentaires expliquent ce que fait le code, il devrait être réécrit pour préciser son intention. C'est ce qu'il entend par code auto-documentant. Souvent, cela peut signifier simplement diviser une fonction longue en éléments logiques plus petits portant 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 comme il est.
Je pense que vous devez toujours vous efforcer de créer du code auto-documenté, car cela facilite la lecture du code. Cependant, vous devez également être pragmatique à propos de certaines choses.
Par exemple, j'ajoute généralement un commentaire à chaque membre de la classe (j'utilise les commentaires de la 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 du code, en particulier du code ancien, cela m'aide à me rappeler rapidement le rôle du député. Je le trouve aussi plus facile que de lire le code et de le résoudre, en particulier si le flux de code fluctue beaucoup .
C'est juste mon opinion. Je connais beaucoup de gens qui travaillent sans aucun commentaire et disent qu'ils trouvent que ce n'est pas un problème. Cependant, j'ai interrogé quelqu'un sur une méthode qu'ils avaient écrite six mois auparavant et ils ont dû réfléchir pendant quelques minutes pour me dire exactement ce qui se passait. 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 refacturez et modifiez les fonctionnalités, vous devez également mettre à jour vos commentaires. Ceci est un argument contre l'utilisation de commentaires car ils sont pires qu'inutiles s'ils sont incorrects.
Indépendamment du fait que du code purement auto-documenté est réalisable, il y a certaines choses qui nous viennent à l'esprit qu'il faut faire de toute façon:
- Ne jamais avoir de code qui est "surprenant". C'est à dire. n'utilisez pas de macro stupides pour redéfinir des éléments, etc. N'utilisez pas abusivement la surcharge de l'opérateur, n'essayez pas d'être intelligent en la matière.
- Scindez le code au bon moment. Utilisez des abstractions appropriées. Au lieu d'inclure un tampon défilant (tampon de longueur fixe, avec deux pointeurs permettant d'obtenir des éléments ajoutés à une extrémité et supprimés à l'autre), utilisez une abstraction avec un nom propre.
- Gardez la complexité de la fonction faible. Si cela devient trop long ou complexe, essayez de le scinder en d'autres fonctions.
Lorsque vous implémentez des algorithmes complexes spécifiques, ajoutez une documentation (ou un lien vers) décrivant l'algorithme. Mais dans ce cas, essayez de redoubler de diligence en éliminant la complexité inutile et en augmentant la lisibilité, car il est trop facile de faire des erreurs.
Je pense que c'est une question de la bonne quantité de documentation, plutôt que tout ou rien. Si les paramètres d’une fonction sont bien nommés, vous n’avez souvent pas à dire exactement ce qu’ils sont, par exemple. char * CustomerName est assez évident. Si vous utilisez des plages de valeurs d'assertion pour les paramètres, vous n'avez pas à documenter ces plages également. OMI, la documentation devrait couvrir tout ce qui n’est pas évident et a donc besoin d’une explication, et la plupart du code a besoin d’une documentation. Personnellement, je préfère voir un exemple illustrant le fonctionnement d’une fonction donnée que la documentation descriptive, dans la plupart des cas.
La documentation à des fins de documentation peut être une perte de temps, car la maintenance de la documentation doit être maintenue à jour avec la base de code. Si personne ne profite de le lire, ne le produisez pas.
J'utilise toujours System.out pour expliquer le code. De cette façon, vous pouvez l’imprimer et le lire à la maison: p
Je retournerais ça.
Demandez-vous ce que vous ne comprenez pas dans son code, puis demandez-lui de les documenter. Et peut-être pourriez-vous aussi nous en dire quelques-uns.
J'ai déjà travaillé avec un type qui était sur le point de vendre une suite financière à une grande entreprise. Ils ont insisté sur le fait qu'il documentait le code source, pour lequel il avait créé une routine d'assembleur de plus de 30 pages, et avait déclaré: "il est documenté, regardez". Excellent produit, excellent implémenteur, mais ...
Quoi qu’il en soit, les commentaires importants ci-dessus ont pour but de définir le contexte. Cet extrait a été déclaré auto-documenté:
> 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)
Mais, pour ma part, j'ai besoin d'un contexte pour bien le comprendre.
On a fait valoir que les commentaires devraient refléter l’intention, mais j’irais un peu plus loin.
Je pense que pour toute classe de problèmes, il existe un vocabulaire idéal (ou presque) et une syntaxe pour le décrire, et vous pouvez le voir si vous demandez simplement à la personne qui a de tels problèmes de les décrire (en supposant que cette personne puisse penser clairement) .
Si ce vocabulaire et cette syntaxe mappent facilement (en définissant des classes, des méthodes, etc.) sur du code dans un langage informatique, alors ce code peut être auto-documenté. En outre, IMO, une langue spécifique à un domaine a été créée. (Et c'est ma définition approximative de "déclaratif".)
À défaut de cet idéal, si le problème ne se retrouve pas directement dans le code informatique, vous avez besoin de quelque chose pour relier les deux. OMI, c'est le but des commentaires.
Ainsi, lorsque le problème change, vous pouvez trouver les parties correspondantes du code à modifier.
EDIT: Je ne discute pas, en passant, en faveur de la méthodologie OOP où chaque nom devient une classe et chaque verbe une méthode. J'ai vu suffisamment de bloatware construits que façon.
Voici mes meilleures réponses à vos questions.
Le code auto-documenté est un code écrit clairement avec des noms de classe, de méthode, de fonction et de variable qui en facilite la compréhension. Si c'est bien fait, c'est la documentation.
Il peut remplace un code bien commenté et documenté, mais je l’ai rarement vu. Trop souvent, les programmeurs pensent qu’ils sont assez bons pour le faire, mais le meilleur moyen de les abattre est de commencer à poser des questions. S'ils doivent commencer à expliquer trop, alors leur code n'est pas assez clair. Vous ne devriez pas avoir à lire le code pour savoir ce qu'il fait.
Il peut y avoir des situations où c'est mieux. Si le code est petit et simple, vous pouvez alors encombrer les choses en ajoutant de la documentation.
Le code contenant un algorithme doit contenir des commentaires. La plupart du temps, même les programmeurs d'origine ne se souviennent pas de ce à quoi ils pensaient il y a quelques mois lorsqu'ils ont écrit une longue fonction.
Ceci est une excellente question. Cela remonte au premier langage de programmation qui permettait les commentaires, j'en suis sûr. Le code devrait certainement être aussi auto-documenté que possible. Les commentaires qui soulignent l'évidence devraient être éliminés. Les commentaires qui facilitent la compréhension de l’intention, du but et de l’utilisation d’une méthode ou d’une section de code donnée peuvent être très précieux pour ceux d’entre nous qui sommes des dolts moins au fait du langage ou du code en question. Les commentaires structurés permettant la génération de la documentation sur les API en sont un bon exemple. Ne commentez simplement pas une instruction IF qui vérifie si une case à cocher est cochée et dites-moi que vous vérifiez si cette case est cochée. Ce qui est évident dans un commentaire, ce sont les pires frappes de déchets de notre univers.
//For example, the above text deals with what is a useful comment
Entrées très mélangées ici, il semble :)
J'utilise le processus de programmation de pseudo-code pour les nouveaux développements, ce qui rend mon code auto-documentant. Je commence à écrire du pseudo-code uniquement lors de l'écriture d'un nouveau code, puis je l'étends. Je ne dis pas que c'est une bonne pratique ou quoi que ce soit du genre, je ne fais que souligner une technique que je trouve utile si vous savez que vous voulez beaucoup de documentation pour votre code s'il est envoyé à un tiers, à un relecteur, etc. souligne parfois des problèmes pour moi avant même que je n'ai écrit une ligne de code.
' check database is available
' if it is then allow the procedure
' if it isnt roll back and tidy up
' move onto something else
devient;
' check database is available
if checkDBStateResult(currentDB) = Open then
' if it is then allow the procedure
proc.Ok = True
else
' if it isnt roll back
proc.Ok = False
CleanUp()
end if
Le code auto-documentant est la bêtise. Quiconque a dû revisiter son code après des semaines, des mois ou des années halète sait cela (ou des jours, dans mon cas). (Peut-être que le type qui fait la promotion de cette idée est encore mouillé derrière les oreilles!?!?!)
Utilisez des noms de données descriptifs significatifs, factorisez votre code de manière intelligente et laissez-vous-vous-expliquer pourquoi vous faites ce que vous avez fait et vous mènerez une vie plus riche et plus épanouissante.
Bien que ... j’ai lu une citation attribuée à Bill Gates: "Le code IS la documentation."
Allez comprendre.
Le code auto-documenté est un code trivialement facile à comprendre. La dénomination de variable contribue grandement à l'auto-documentation du code, mais je trouve que la meilleure tactique consiste à décomposer toute logique compliquée en minuscules morceaux et à reformuler cette information en méthodes séparées avec des noms verbeux et informatifs. Ensuite, vos méthodes compliquées deviennent simplement une liste d'étapes à exécuter. Les minuscules méthodes d'assistance privée sont ensuite suffisamment documentées par leur propre nom et les méthodes compliquées sont documentées sous forme d'une séquence d'étapes abstraites à exécuter. En pratique, cette stratégie ne peut pas toujours être appliquée à la perfection, les commentaires sont donc toujours très utiles. De plus, vous ne devriez jamais abandonner complètement un outil qui vous aiderait à écrire un code plus facile à comprendre.
Un code auto-documenté est un code tellement clair qu'un commentaire serait inutile. Je vais donner un petit exemple:
//iterate from 0 to 100
for(int i=0; i < 100; i++) {
println i
}
Le commentaire est plutôt inutile, car le code est clair. La documentation est une bonne pratique, mais une documentation supplémentaire peut ajouter du bruit inutile au code. Ce que votre collègue doit savoir, c'est que tout le monde ne peut pas lire le code des autres et reconnaître tous ses détails.
int calc(int a, int b) {
return sqrt(a*a + b*b); //pythagoras theorem
}
Le dernier extrait serait extrêmement difficile à déchiffrer sans le commentaire. Vous pouvez imaginer d'autres exemples plus artificiels.