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

https://stackoverflow.com/questions/209015

03-07-2019
|

Question

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, même s'il est plus clair que le code que j'ai vu d'autres producteurs, 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.

Qu'est-ce que le code auto-documentant
Peut-il vraiment remplacer un code bien commenté et documenté
Existe-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 s'auto-documenter sans commentaires

C’est peut-être juste mes propres limites, mais je ne vois pas en quoi cela peut être une bonne pratique.

Cela n’est pas censé être un argument - évitez d’évoquer les raisons pour lesquelles un code bien commenté et documenté est une priorité absolue - 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.

De même, ceux d'entre vous qui plaident contre le code auto-documenté - 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 votent à contre-sens si vous ne restez pas sur le sujet.

La solution

À mon avis, tout code devrait être auto-documenté. Dans un bon code auto-documenté, vous n'avez pas à expliquer chaque ligne car chaque identificateur (variable, méthode, classe) a un nom clair sémantique . 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 les parties du code qui ne sont pas 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 en boucle fichiers dans un répertoire, teste si la taille du fichier est supérieure à 10 Mo, retourne si vrai )

son code et sa documentation vont bien, à mon avis. Notez que le code auto-documenté ne ne 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 " auto-documentant " Le code prend plus de temps à comprendre que le code commenté, il n’est pas vraiment auto-documenté.

Autres conseils

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);

À ce code auto-documentant, qui indique ce qui 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 du 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 votre ami parle quand 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 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 récente de ce que fait votre code, mais à mon avis, il est très difficile pour lui d'expliquer l'intention , qui est la plus vitale aspect des commentaires. Si le texte est écrit correctement, nous savons déjà ce que fait le code, nous devons simplement savoir pourquoi diable il le fait!

Quelqu'un a déjà dit

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 "l'auto-documentation" le code, c’est que la logique du programme dans le code est suffisamment claire pour expliquer à toute personne qui lit le code, non seulement ce qu’il 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 expliquer la logique derrière ce qui se passe, mais il ne peut pas expliquer la raison , d’une certaine manière, en particulier s’il existe plus d’une façon de résoudre un problème. Pour cette seule raison, il ne pourra 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 d'amdfan de "correctement commenté". code:

/* 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 le texte ci-dessous est tout aussi informatif dans la plupart des systèmes logiciels modernes et reconnaît explicitement que le 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);

Dans ma propre expérience personnelle, il y a très peu de "normaux" situations de codage où 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 de sorte 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 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 te répète 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 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 existe certaines 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 les informations contenues dans 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.

Ceci étant dit, les commentaires peuvent être très utiles pour les nouveaux venus, 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 une 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, cette partie de code est auto-documentée:

print "Hello, World!"

et c’est le cas:

factorial n = product [1..n]

et c’est le cas:

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 de " lecteur averti " est très subjectif et situationnel. 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 pouvoir appeler le code en auto-documentation.

Le meilleur argument que j'ai vu pour l'écriture de "code auto-documenté". est-ce que cela é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, bien que le code puisse décrire ce et comment il se débrouille tout seul, il ne peut pas expliquer pourquoi quelque chose se passe d'une certaine manière .

Dans l'ordre:

Un code auto-documenté est un code qui exprime clairement son intention au lecteur.
Pas tout à fait. Les commentaires sont toujours utiles pour commenter pourquoi une stratégie particulière a été choisie. Cependant, les commentaires qui expliquent le fonctionnement d’une section de code indiquent un code insuffisamment auto-documenté et qui pourraient nécessiter 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 du code ne pourrait pas être expliqué suffisamment clairement sans commentaires; Cependant, comme je l’ai dit plus tôt, il est parfois nécessaire / utile d’inclure des commentaires sur le pourquoi .

Cependant, il est important de noter qu'un code réellement auto-documenté nécessite beaucoup de discipline de soi et d'équipe. Vous devez apprendre à programmer de manière plus déclarative, et vous devez être très humble et éviter "malin". code en faveur du code qui est si évident qu'il semble que n'importe qui aurait pu l'écrire.

Premièrement, 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 diffère 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;
 }

Néanmoins, 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é", tu vois 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 des tâches de maintenance, ces informations sur l'arrière-plan deviennent très importantes.

Juste ma pincée de sel ...

Vous voudrez peut-être signaler à votre collègue que, peu importe son degré d'autodocumentation, si d'autres solutions étaient 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 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 au fil du temps.

Avez-vous entendu parler de "WEB" de Donald Knuth? projet de mettre en œuvre son concept de Programmation littéraire ? 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.

La différence se situe entre " quoi " et "comment".

Vous devez 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 particulier). Cela 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 celui qui le maintient est un maniaque homocide qui sait où vous habitez."

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 ya un mois ou deux que j’ai écrit un article de blog entier décrivant mon point de vue. Publiez ici .

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

Toutefois, ce "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 croyait fermement en cette théorie En fait, la meilleure chose que je me souvienne de lui: "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 la suivante: même si vous êtes capable de comprendre ce qui se passe dans le code, mais quelqu'un de moins expérimenté peut vous suivre 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’elles sont importantes, mais il est très rare que les commentaires ne soient pas nécessaires.

Je suis surpris que personne n'ait provoqué la " programmation alphabète " ;, a technique mise au point en 1981 par Donald E. Knuth de TeX et "The Art of Computer Programming". renommée.

Le principe est simple: puisque le code doit être compris par un humain et que le compilateur rejette les commentaires, pourquoi ne pas donner à chacun la chose dont il a besoin - une description textuelle complète de l’intention du code, sans entrave les exigences du langage de programmation, pour le lecteur humain et le code pur pour le compilateur.

Pour ce faire, les outils de programmation alphabétiques vous fournissent un balisage spécial 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 lire il.

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: -)

Mon avis est écrit dans cet article:

Le seul conseil pour documentez votre code.

Extrait:

Au lieu d'écrire beaucoup de commentaires   pour expliquer les comportements subtils de   votre programme, pourquoi ne pas restructurer votre   des logiques pour qu'elles vont de soi?   Au lieu de documenter ce qu'est une méthode   fait, pourquoi ne pas choisir un nom clair   pour cette méthode? Au lieu de taguer   votre code pour indiquer le travail inachevé,   pourquoi ne pas simplement jeter un   NotImplementedException ()? Au lieu de   inquiétant si vos commentaires sonnent   assez poli à votre patron, votre   collègues ou quiconque lisant le code,   pourquoi ne pas simplement arrêter de s'inquiéter en ne   les écrire du tout?

Plus votre code est clair, plus il est facile   c'est de le maintenir, de l'étendre, de   travailler sur les éditions futures. le   moins votre code est ordored, moins   besoin il est de commenter. Le plus   les commentaires, plus le   Coût de maintenance.

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 en cours d'exécution. Les langages de programmation sont à notre avantage. Nous ne voulons pas écrire assemblé. Nous devons comprendre ce que nous écrivons. La programmation consiste à écrire du code.

Si vous pouviez 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 pour les 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 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é est omniprésente 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é 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 devrait être aussi facile et clair à lire comme possible.
Les commentaires doivent motiver décisions de conception que j'ai prises, comme: pourquoi est-ce que j'utilise cet algorithme, ou limitations du code a, comme: fait ne fonctionne pas quand ... (cela devrait être traité dans un contrat / assertion dans le code) (généralement dans la fonction / procédure).
La documentation devrait lister l'utilisation (convocations), côté effets, 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 en dehors de la fonction / procédure, mais proche de la code qu'il décrit.

Cela signifie que les trois méthodes de documentation du code cohabitent étroitement 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 le code soi-disant auto-documenté est qu’il transmet ce qu’il fait réellement. Certains commentaires peuvent aider quelqu'un à mieux comprendre le code (par exemple, les étapes de l'algorithme, etc.), mais il est dans une certaine mesure redondant et je doute que vous convaincriez 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.

Etre capable de déterminer qu'un code fait X d'un coup d'œil est bien 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 a l'air bien, est évident, mais ne couvre pas 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 substitut pour 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 fonctions ou de variables afin de les rendre plus explicatifs. C’est peut-être au codeur de décider s’il va combler le manque à gagner avec un commentaire ou bien renommer certaines variables et fonctions ainsi que le code de refactoring.

Cependant, elle ne peut pas vraiment remplacer votre documentation, car c’est ce que vous donnez à d’autres pour expliquer comment utiliser votre système, plutôt que de la même manière.

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 ... a besoin de quelques commentaires pour dire quoi vous faites dans ce cas;)

Lors de la rédaction d'un code mathématique, j'ai parfois trouvé utile de rédiger de longs commentaires ressemblant à des rédactions, 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 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. Certains codes peuvent être écrits si clairement qu'ils n'ont pas besoin 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. Écrivez-le aussi clairement que possible, puis utilisez autant de commentaires que nécessaire ...

Je dirais, comme beaucoup d’entre vous, que pour être vraiment auto-documenté, le code doit montrer une 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 disposiez de 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

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

Le code que vous consultez a été généré automatiquement. Par conséquent, toute modification apportée au code pourrait être annulée 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.)

Tout va être dans les valeurs de l’équipe 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: cela va de soi, 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

BinarySearch

BinaryChop

Ces trois méthodes fournies 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 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, essayez d'organiser votre code de la manière suivante:

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, il reste donc à documenter les abstractions principales de votre système, 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.

Licencié sous: CC-BY-SA avec attribution

Non affilié à StackOverflow