Code d'auto-documentation contre. Code commenté


22

J'ai effectué une recherche mais je n'ai pas trouvé ce que je cherchais, n'hésitez pas à me lier si cette question a déjà été posée.

Plus tôt ce mois-ci, ce message a été publié:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

Pour résumer, vous êtes un mauvais programmeur si vous n'écrivez pas de commentaires. Mon opinion personnelle est que le code doit être descriptif et ne nécessite généralement pas de commentaires, à moins que le code ne puisse pas être auto-descriptif.

Dans l'exemple donné

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

L'auteur a déclaré que ce code devrait être commenté, mon opinion personnelle est que le code devrait être un appel de fonction descriptif:

$extension = GetFileExtension($image_filename);

Cependant, dans les commentaires, quelqu'un a fait cette suggestion:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

L'auteur a répondu en disant que le commentateur était "une de ces personnes", c'est-à-dire un mauvais programmeur.

Quels sont les points de vue de tout le monde sur le code d'auto-description vs le code de commentaire?


1
@ Péter - J'ai jeté un coup d'œil à celui-ci, mais je voulais plus obtenir l'opinion personnelle des gens entre les deux, plutôt que de définir les commentaires comme des codes ou non.
Phill

2
Je trouve cet article ... horrible à lire. Très insultant.
sevenseacat

@Karpie - Est-ce que j'ai fait :(
Phill

3
"Pourquoi vous êtes un mauvais programmeur PHP" Réponse: Parce que vous programmez en PHP.
Thomas Eding

Votre méthode préférée consiste essentiellement à utiliser des appels de fonction pour commenter votre code. Pourquoi ne pas utiliser les commentaires pour ça? Les fonctions doivent être utilisées uniquement pour du code réutilisable. Personnellement, je déteste devoir suivre le code de quelqu'un d'autre écrit de cette manière pour la même raison que la déclaration GOTO est mauvaise - elle crée du code spaghetti. Cela est amélioré par les IDE modernes, mais tous les langages et programmeurs ne peuvent pas utiliser ces IDE et c'est toujours désorientant. Honnêtement, je conviens que vous devriez commenter des sections de code qui ne sont pas claires en un coup d'œil - cela rend la lecture de votre code tellement plus rapide et plus facile.
dallin

Réponses:


46

Je préfère écrire du code auto-documenté. Un guide pour cela est Clean Code .

Bien sûr, cela ne signifie pas qu'il ne faut jamais utiliser de commentaires - ils ont leur rôle, mais à mon humble avis, vous devez les utiliser avec précaution. Cette réponse antérieure à moi sur SO explique plus en détail mes réflexions sur le sujet.

Bien sûr, comme l'a noté @Niphra, il vaut toujours la peine de vérifier que ce que je pense être propre est vraiment compréhensible par les autres. Mais c'est aussi une question de pratique. De retour à l'université, j'ai écrit des morceaux de code cryptiques simplement en raison de l'utilisation de noms étranges et drôles pour toutes les entités de code, selon mon caprice. Jusqu'à ce que mon professeur rejette une de mes tâches, notant poliment qu'il ne pouvait pas déterminer quel module était le principal :-) C'était une bonne leçon, alors je me suis efforcé de me concentrer sur l'écriture de code toujours plus lisible depuis. De nos jours, je reçois à peine les plaintes des coéquipiers.


J'adore ce livre :)
Phill

Je trouve toujours des commentaires utiles pour exprimer la stratégie utilisée, et ceux qui ont été rejetés (avec la raison). Je suis d'accord que les micro-commentaires sont généralement inutiles.
Matthieu M.

9
L'une de mes citations préférées de Clean Code est que chaque commentaire est un échec à s'exprimer dans le code.
Doval

6
@Doval: Une philosophie intéressante, au moins en ce qui concerne les commentaires au sujet de ce Code fait . D'un autre côté, certains des commentaires les plus utiles peuvent être ceux sur la raison pour laquelle le code ne fait rien - un concept que je ne pense pas que le code devrait être censé exprimer.
supercat

1
Pas du tout d'accord. Aucune quantité de dénomination ne va décrire complètement le but de la logique.
Kolob Canyon

65

Vous ne devez pas documenter ce que fait le code, mais vous devez expliquer pourquoi il le fait.

Aucune astuce de dénomination n'exposera le pourquoi et le pourquoi, vous devez donc ajouter des commentaires pour expliquer le but des différents morceaux de code.

Tous les autres commentaires peuvent être supprimés en toute sécurité.


3
+1 L'exemple de l'article lié dit "faites des commentaires dans toute situation où le but du code que j'ai écrit n'est pas immédiatement apparent". - Il est juste stupide de croire que le code peut à lui seul communiquer un but , car les machines elles-mêmes n'ont aucun concept de but. Contre exemple: nous avons des bogues dans presque tous les logiciels jamais écrits, c'est un truisme. Si un ordinateur comprenait le but (le pourquoi ), il refuserait simplement de faire autre chose que ce que nous voulions, plutôt que de recréer consciencieusement le quoi / quand / comment / où cela a conduit au bogue.
David Meister

Tout le code à l'intérieur d'une fonction doit être là pour remplir le but de la fonction, c'est-à-dire ce qu'elle fait, par exemple écrire du texte dans un fichier, la fonction "writeTo (texte de chaîne, fichier fichier)". Si un code a un objectif différent, par exemple vérifier les conditions préalables, comme vérifier que le fichier existe ET qu'il n'est pas évident, alors peut - être une meilleure idée qu'un commentaire est d'écrire une nouvelle fonction, par exemple "checkWritable (fichier fichier)". La qualité du code n'est pas une liste de contrôle dogmatique, mais si elle a besoin de commentaires, c'est un mauvais signe, et les «pourquoi» ne sont pas une bonne raison d'en avoir besoin . Pourquoi le poulet a-t-il traversé la route?
Trylks

2
@Trylks Cela fonctionne pour certains cas mais pas pour tous. Imaginez ce scénario: for (int i = 0; i < length/2;i++) { //if length is odd, the middle element should stay in place. Maintenant, ce n'est pas quelque chose qui est évident d'après le but de la fonction englobante, ni ne pourrait être pris en compte dans sa propre fonction. Si vous ne le commentez pas, c'est clairement mauvais. Vous ajoutez donc un commentaire pour clarifier votre intention.
biziclop

2
@Trylks En outre, même si nous prenons votre exemple, vous intégrez votre vérification dans une méthode et vous l'appelez, parfait. Il ne vous reste plus qu'à expliquer pourquoi vous devez vérifier que le fichier est accessible en écriture. :)
biziclop

38

Je ne crois pas vraiment au code auto-descriptif. Il y a du code plus lisible et du code moins lisible , selon la langue, votre connaissance de celui-ci (en tant qu'auteur d'origine), la connaissance du gars qui le lit et la fonction du code. Mais non, quand même ... il faut le décrire avec un petit commentaire.

Ce qui est clair pour moi maintenant, que je suis dans ce domaine de réflexion ne sera probablement pas clair pour moi dans un an, quand je pense à quelque chose de complètement différent et que je dois utiliser à nouveau cette partie du code.

Alors, commentez votre code. Pas toutes les lignes (mon Dieu, non) bien sûr, mais mettez quelques lignes de commentaires au-dessus d'une fonction / sous-routine / module , ou une partie particulièrement délicate et dites en bref ce qu'il fait. Vous vous remercierez dans un an ou deux.


J'y suis allé, j'ai fait ça. Le «code moins lisible» devrait être amélioré en un code qui se lit bien. La connaissance d'une langue ne compte pas vraiment: quand vous n'êtes pas familier avec la syntaxe, vous devez d'abord l'apprendre - franchement, c'est la base pour être un professionnel. Essayer de compenser un code terrible en ajoutant des commentaires n'est pas une bonne idée. Les commentaires ne doivent jamais tenter de décrire ce que fait le code. Un commentaire (général) n'est justifié que si vous avez besoin de dire le pourquoi et non le quoi . Tout le reste n'est que du bruit et des choses supplémentaires inutiles à entretenir.
Powerslave

PS, je sais que j'ai un peu 'zombié' :) Désolé pour ça
Powerslave

Pour éviter toute confusion, je parle du cas habituel, lorsque vous n'êtes pas obligé d'écrire du mauvais code par les exigences de l'entreprise (par exemple, performances exceptionnelles ou ajustement dans un stockage confiné). Dans d'autres (rares) cas, vous n'avez pas d'autre choix que de laisser des commentaires, allégeant quelque peu le fardeau de la prochaine victime.
Powerslave

19

Heureusement, les deux camps sur cette discussion sont représentés ici, et les arguments pour et contre pour les deux ont été mentionnés.

Je crois que les deux camps ont des arguments qui se chevauchent, et sont en fait d'accord sur la plupart d'entre eux, la façon de les atteindre est un peu différente.

Arguments qui se chevauchent

  • Le code doit être lisible.
  • Les commentaires ne doivent pas dire exactement la même chose que le code, mais donner un aperçu supplémentaire si nécessaire.
  • Tous les noms de variables / fonctions doivent être mûrement réfléchis afin qu'ils donnent une bonne représentation de ce qu'ils sont / font.
  • Le code en double doit être évité.

Maintenant, la principale différence est le poids accordé à certains de ces arguments.

Code auto-descriptif

  • Les commentaires peuvent devenir obsolètes, donc minimisez leur utilisation, car les mauvais commentaires sont pires que pas de commentaires.
  • Les commentaires sont une duplication du code. Tout ce qui peut être écrit en code doit être écrit en code.

Plus de commentaires

  • Les commentaires sont plus lisibles que le code. Un anglais simple est meilleur pour décrire quelque chose.

  • Le code clair provoque souvent une ambiguïté qui doit être commentée de toute façon. Essayer de décrire cela dans le code entraîne des noms trop longs. De plus, vous êtes constamment confronté à ces informations «supplémentaires» dont vous n'avez besoin que la première fois que vous les rencontrez.

Je crois que les deux camps ont des arguments très valables, mais vous ne devriez pas suivre frénétiquement un camp, juste parce qu'il résout un problème.

Pour démontrer, dans le livre Clean Code , le code est décomposé en de nombreuses méthodes plus petites qui ne sont appelées qu'une seule fois. Les méthodes sont créées pour la seule raison de documenter le code (et TDD plus facile). Il en résulte un enfer fonctionnel . Le code est moins lisible qu'il ne l'était à l'origine, et lors de la refactorisation, aucune pensée n'a été donnée pour encapsuler le code réutilisable.

D'un autre côté, vous voyez souvent des API où chaque fonction est commentée, simplement parce que «les commentaires sont bons». Les choses qui auraient dû être commentées ne le sont toujours pas.


1
@Steven - "D'un autre côté, vous voyez souvent des API où chaque fonction est commentée, juste parce que 'les commentaires sont bons'. Les choses qui auraient dû être commentées ne le sont toujours pas." Ugh, tellement frustrant vrai!
dss539

C'est une très bonne réponse! Une chose, si cela ne vous dérange pas, sur la lisibilité des commentaires: Personnellement, je ne crois pas que les commentaires soient plus lisibles. En tant que développeurs, nous pensons généralement en code source, en particulier en "mode de codage". Dans ces moments, l'imprécision du langage humain ordinaire est généralement plus une distraction qu'une aide.
Powerslave

5

"Je suis désolé mais tu es ce mec."

Je me demande pourquoi il n'aime pas commenter: P

Sérieusement, le codage est trop un art que l'on pourrait véritablement faire une déclaration aussi radicale. Parfois, vous avez besoin de commentaires, parfois de fonctions plus nombreuses et mieux nommées. Habituellement les deux.

Recherchez la programmation alphabétisée comme un style extrême.


Ouais. Je veux dire, si Donald Knuth pense que vous avez non seulement besoin de commentaires, mais que vous en avez parfois besoin de chapitres , j'y réfléchirais au moins deux fois avant d'être en désaccord.
PeterAllenWebb

3

La réponse courte, meilleure et correcte

L'idée qu'un "code auto-documenté" bien écrit est tout ce dont vous avez besoin est un anti-modèle et devrait mourir, même s'il fait des exceptions pour les commentaires qui expliquent "pourquoi". C'est un mythe que vous pouvez toujours écrire tout le code pour n'importe quel algorithme suffisamment clair pour que n'importe quel programmeur puisse le regarder et l'obtenir (ou qu'il ne nécessite pas de refactoring ou de temps d'organisation que vous n'avez pas). Plus important encore, le plus souvent, les programmeurs qui pensent écrire du code clair ne le font pas.

Une réponse bien meilleure que les commentaires ne devrait être utilisée que pour expliquer "pourquoi" est que les commentaires devraient:

  • expliquer "pourquoi" (bien sûr)
  • expliquer "quoi" sur des lignes individuelles uniquement lorsque le code est complexe ou que le but n'est pas clair et qu'il ne peut ou ne vaut pas la peine d'être simplifié davantage
  • expliquer "quoi" pour les blocs de code pour accélérer la compréhension et trouver ce dont vous avez besoin

L'explication pour le sauvegarder

Les gens pensent à tort que la seule raison pour laquelle les gens utilisent des commentaires est d'expliquer ce que signifie une ligne de code. La vérité est qu'un objectif important de commenter le code est de le rendre plus rapidepour parcourir votre code et trouver ce que vous cherchez. Lorsque je reviens au code plus tard ou que je lis le code de quelqu'un d'autre, bien sûr, je peux lire et comprendre une section de code bien écrit - mais n'est-il pas plus rapide et plus facile de lire le commentaire en haut en disant ce que fait cette section de code et sauter complètement si ce n'est pas ce que je recherche? Pourquoi rester assis et comprendre le code, même s'il est bien écrit, si vous pouvez jeter un coup d'œil à quelques commentaires et comprendre une fonction entière? C'est pourquoi nous utilisons des noms descriptifs pour les fonctions - personne ne dit que je n'ai pas besoin d'utiliser un nom descriptif pour ma fonction parce que quelqu'un peut simplement parcourir mon code écrit clairement pour voir ce qu'il fait.

Par exemple, si je regarde à travers la fonction de quelqu'un d'autre, est-il plus facile de parcourir ligne par ligne le code pour voir ce qu'il fait ou de regarder trois commentaires bien écrits dans la fonction pour voir exactement ce que fait la fonction et où ça le fait?

Un autre anti-modèle est la surutilisation des fonctions pour commenter votre code. Les fonctions bien nommées sont une partie importante de la documentation du code, mais parfois les programmeurs séparent 2 à 3 lignes de code qui ne seront jamais utilisées nulle part ailleurs dans une fonction à des fins de documentation. Pourquoi la surutilisation des fonctions est-elle meilleure que la surutilisation des commentaires? L'utilisation de fonctions comme celle-ci équivaut à adopter des instructions GOTO - cela crée du code spaghetti qui peut être pénible à suivre.

Essentiellement, lorsque vous travaillez dans un environnement d'entreprise, où les gens partagent constamment du code et où les gens n'ont pas toujours le temps de rendre leur code parfait, quelques bons commentaires peuvent économiser des tonnes de temps et de frustration. Et rappelez-vous, bien que vous puissiez être un gourou qui peut lire le code à une vitesse légère, tout le monde dans votre bureau ne l'est probablement pas.


Je déteste quand les gens votent et ne laissent même pas de commentaire pourquoi. Avez-vous même lu l'intégralité du message? Qu'est-ce qui n'est pas simple et vrai? Avec quoi êtes-vous en désaccord? J'ai l'impression que les gens sont tellement attachés à leur idée ou à ce qu'ils lisent qu'ils n'y pensent même pas et vont immédiatement rejeter tout ce qui ne partage pas leur point de vue.
dallin

3
Je suppose que c'est parce que vous rejetez carrément et nommez quelque chose d'anti-modèle qui est presque universellement reconnu comme étant juste. Je pense certainement que vous allez trop loin. Surtout, je ne peux pas imaginer faire confiance aux commentaires aussi bien que vous semblez le faire. Si vous lisez à l'aveugle les commentaires et non le code, les commentaires peuvent être erronés et obsolètes, et vous ne le sauriez jamais. C'est la base de l'utilisation des fonctions comme documentation. Je conviens que vous ne devriez pas avoir trop de fonctions au même endroit, bien que la solution à cela ne soit définitivement pas de les remplacer par des commentaires.
Magus

@Magus Merci pour le commentaire. Je suppose que vous parliez de mon utilisation des fonctions comme documentation. En relisant cela, je crois que je l'ai mal formulé pour sonner comme si je voulais dire que l'utilisation de fonctions à cette fin (par opposition à la surutilisation des fonctions à cette fin) était mauvaise. J'ai nettoyé ce paragraphe pour clarifier mon intention initiale. Ma réflexion sur la confiance dans les commentaires est que si un commentaire devient obsolète, c'est généralement un signe que vous commentiez trop étroitement une section de code - que vous commentiez la mise en œuvre plutôt que l'intention.
dallin

but isn't it faster and easier to read the comment at the top saying what that section of code does and skip it altogether if it's not what I'm looking forCela s'appelle "le nom de la méthode / fonction". Si vous avez un bloc de code sans nom mais si long que vous ne pouvez pas le prendre en un coup d'œil, le problème réside peut-être là.
biziclop

1
@biziclop Overtime J'en suis venu à croire que cet argument est principalement sémantique, et dans la pratique, notre code se ressemblerait. Cela dit, en supposant que le bloc de code n'est pas utilisé à plus d'un endroit, je ne vois pas de différence entre un bloc de code avec un bref commentaire descriptif en haut et un bloc de code avec un court nom de fonction descriptive en Haut. Ce sont les mêmes, sauf qu'on n'a pas d'espace. Ils peuvent être à la fois faux et obsolètes. La seule différence que je vois vraiment est que le code est plus facile à lire avec un commentaire car vous n'avez pas à suivre l'appel de fonction à un emplacement séparé.
dallin

2

Eh bien, vous devez également vous souvenir de quelque chose qui est évident ou "auto-documenté" pour vous, peut-être pas pour quelqu'un d'autre ... Peut-être quelqu'un avec moins de compréhension de certaines fonctions. Je commente donc à peu près tout.


1
Pouvez-vous donner un exemple. Je veux dire donné l'exemple dans ma question initiale. "GetFileExtension" quel est le point dans le commentaire "Obtient l'extension de fichier d'un fichier donné"? La méthode a déjà décrit ce qui devrait entrer dans le commentaire. Si la méthode était nommée "GetExtension", un commentaire aiderait à clarifier ce que la méthode doit faire, car la méthode ne s'explique pas d'elle-même.
Phill

+1 Il s'agit d'une question de connaître votre audience. Qui est susceptible d'utiliser cette fonction? Comment pouvez-vous les aider? Que vaudra votre aide? Vaut-il mieux que de passer un peu de temps maintenant pour ajouter un commentaire? Etc. Etc. Etc.
PeterAllenWebb

2
@PeterAllenWebb: Aucun point à ce commentaire. Cela ne signifie pas à distance que la fonction ne doit pas être commentée; cela devrait. "Extension" inclut-elle le point ou non? À quoi sert la valeur de retour "foo"? ( null?? "") Pour "foo."? Le passage nullprovoquera-t-il une exception ou la fonction retournera-t-elle quelque chose (peut-être null)?
TJ Crowder du

2

Eh bien, le code auto-documenté est que dans cette fonction, vous trouverez:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

ce qui est explicite lorsque vous avez le nom de la fonction car il ne s'agit que de deux lignes. Lorsque les choses se compliquent, vous devez soit encapsuler toutes les quelques lignes de code dans une fonction avec un nom descriptif, soit utiliser des commentaires si nécessaire .

Je n'ai jamais compris pourquoi cela devrait être une ou / ou une question, au lieu de et / et. Oui, faites en sorte que votre code soit le plus documenté possible, et oui, ajoutez des commentaires aux parties qui, autrement, ne seraient pas assez clairs.


Ouais. Je pense qu'il faut être "entraîné" pour penser que ça devrait être l'un ou l'autre et pas les deux.
PeterAllenWebb

2

Les commentaires et le code propre auto-documenté sont différents. Le code concerne la façon de faire les choses. Et les commentaires doivent couvrir la partie pourquoi , qui ne peut pas être expliquée dans le code, quelle que soit votre langue. De plus, si votre langue est très limitée et que vous n'avez aucun contrat, aucune spécification statique et même aucune assertion, les commentaires doivent couvrir les problèmes de limites de votre code.


En supposant qu'il y ait une raison à tout, cela devrait être commenté?
JeffO

Oui, précisément. C'est pourquoi je crois que la meilleure façon de commenter votre code est une programmation alphabétisée.
SK-logic

1

Dans ce cas, il est facile de créer une fonction descriptive. Mais j'ai lu beaucoup de code créé par de bons programmeurs qui pensaient que leur code était auto-documenté, et ce qui avait été clair pour eux était vraiment déroutant pour moi.

$ extension = GetFileExtension ($ image_name);

Pour revenir à votre exemple, puis-je lui envoyer un tableau de noms d'images ou ne prend-il qu'une seule image? Prend-il en charge tous les types de fichiers, ou seulement certains d'entre eux? Sera-t-il sécurisé la chaîne pour moi, ou dois-je le faire? Si le type de fichier n'existe pas, m'en informe-t-il?

Bien sûr, j'étire un peu celui-ci. Mais je me souviens d'un programmeur qui croyait que audio_bandwidth et video_bandwidth étaient des noms auto-documentés; s'est avéré que l'audio devait être exprimé en octets et la vidéo en kilo-octets. Il a fallu beaucoup de temps pour comprendre celui-là.


5
Vous étirez beaucoup celui-là. La fonction obtient l'extension du nom de fichier. Ni plus ni moins. Son nom indique s'il prend un tableau ou non (clairement pas). Je ne peux pas penser à une méthode qui s'appuierait sur le type de fichier pour obtenir l'extension. La sécurisation de la chaîne est la seule qui pourrait être incorporée, mais je ne m'y attendrais jamais car comme tout développeur PHP le sait: toutes les entrées utilisateur sont suspectes, alors sécurisez-la avant de l'utiliser.
Matt Ellen

2
@Matt: Le «clairement non» indique que vous ne faites pas de maintenance très souvent. Être explicite permet d'économiser plus de tête (et RTFSource) plus tard, et cela documente également ce que l'auteur d'origine s'attendait à ce qu'il fasse. Que ce soit dans un commentaire ou dans un nom de fonction long n'est pas si important.
Donal Fellows

Peut-être que l'exemple était mauvais à utiliser dans cette question, je n'ai pas touché PHP depuis environ 7 ans, je fais du C # et un tout petit peu de Java, donc j'ai l'habitude d'avoir un IDE qui me dit le type retourné ou déclarant les types.
Phill

1
@Donal Fellows: il est dit fichier, singulier. Qu'est-ce qui est ambigu là-dessus? C'est complètement explicite.
Matt Ellen

4
Le fait qu'il y ait maintenant 7 réponses de 4 personnes discutant de l'évidence ou non d'un seul appel de fonction me suggère que vous devez utiliser des commentaires . Cela met également en évidence le fait que la dénomination précise est une forme d'art en soi.
Ant le

1

L'un n'exclut pas l'autre. Même si votre code est auto-commenté, il peut arriver que vous ayez besoin de commentaires réguliers pour expliquer pourquoi votre code auto-commenté fait ce qu'il fait.


Je pense que cela tombe dans mon opinion qui était "le code doit être descriptif et ne nécessite généralement pas de commentaires sauf si le code ne peut pas être auto-descriptif". Si vous écrivez du code qui est bien écrit, n'explique pas complètement l'intension du code, alors les commentaires aident à rendre le code plus descriptif.
Phill

Le code ne peut jamais expliquer son objectif. Lorsque vous voyez un marteau, vous ne pouvez pas savoir à quoi il sert - que ce soit pour briser des crânes ou simplement pour forger un fer brut.
SK-logic

1
@ SK-logic:public <T> void hit(T item);
Michael K

@Michael - exactement. Comment l'utilisateur déterminera-t-il quelles catégories d'objets peuvent et doivent être martelées? Même avec un système de type bien meilleur, il n'est pas toujours clair, quelle gamme d'utilisations possibles est réellement planifiée par un développeur.
SK-logic

1

Je ne suis pas d'accord avec cet article et je suis d'accord avec vous dans une certaine mesure. Si vous utilisez de bons noms de méthode, de bons noms de variable et une petite méthode qui font une seule chose, le code devrait être simple à suivre.

Essayez simplement de ne pas être intelligent, car le code intelligent est horrible à lire et à maintenir. Mot-clé: maintenir !

À mon avis, les commentaires devraient décrire le pourquoi et non le quoi. Rappelez-vous que dans ce monde hypothétique parfait, votre code est suffisamment propre pour permettre une lecture facile, vous n'avez pas besoin d'expliquer ce qu'il fait, mais pourquoi vous avez choisi de le faire de cette façon ou de cette façon.

Si vous utilisez un système de contrôle de source, vous pouvez utiliser le message de validation pour faire savoir à tout le monde (et à vous-même) ce que vous avez fait à un moment donné et, plus important encore, pourquoi.


1

Vous voudriez éviter d'écrire des commentaires comme vous voudriez éviter toute documentation. En ce qui concerne le langage de programmation lui-même, tout le monde fonctionne à partir du même ensemble de vocabulaire et de syntaxe (presque).

Lorsque votre application est destinée à un domaine particulier, il peut être difficile d'amener tout le monde à s'entendre et / ou à établir un vocabulaire commun. On nous apprend à éviter les abréviations et le jargon étendu, mais je vais l'appeler

EBITDA

et pas

EquityBeforeInterestTaxesDepréciationAndAmortization

Si vous n'en connaissez pas, vous ne comprenez probablement pas l'autre. Si la société a une implémentation rare, un commentaire aiderait le prochain programmeur qui pourrait avoir de l'expérience dans le domaine, mais pas cette entreprise en particulier (ce qui rend les choses plus compliquées.).


1

Je pense que nous devons faire la distinction entre la documentation et expressivité du code.

Lors du débogage ou de la révision du code, vous ne lisez pas un livre. La plupart du temps, vous voulez simplement passer d'une méthode à l'autre et établir des connexions rapides dans votre esprit pour avoir une compréhension de base de ce qui se passe au moment de l'exécution. Ce n'est pas la documentation autour du code mais le expressivité des signatures de code qui importe dans ce processus, leur capacité à être suffisamment significative pour que vous puissiez les identifier immédiatement et les ajouter à votre propre pile d'appels internes. À ce stade, notre cerveau (du moins, le mien fonctionne de cette façon;)) a tendance à considérer les gros blocs de commentaires comme un bruit plutôt que comme une aide. Par conséquent, des commentaires sur une seule ligne, ou mieux encore, des noms de méthode et d'objet auto-descriptifs suffisent ici.

Si vous voulez "lire le livre" d'une classe ou d'une fonctionnalité particulière, c'est bien mieux dans les tests unitaires. Les tests unitaires bien conçus sont par nature révélateurs d'intentions et beaucoup plus documentés (c'est-à-dire explicatifs, détaillés) que les blocs de commentaires les plus épais car ils contiennent 1 / les attentes sur ce que ce code est censé faire et 2 / la capacité de vérifier ces attentes contre le vrai code. Un test de réussite est cent fois plus fiable que n'importe quel commentaire en termes de documentation, car il prouve que ce qu'il affirme est vrai.


1

Certains codes ne sont tout simplement pas auto-documentés et nécessitent des commentaires d'un collègue humain qui a compris et testé cette pièce. Ce que j'ai ci-dessous n'est pas suffisant pour le comprendre, je pense.

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}

1

Je préfère généralement écrire du code auto-documenté, avec des commentaires peu clairs, car je pense que la plupart du code ne se documentera pas complètement.


0

À l'université, on nous a appris à reformuler à peu près chaque ligne de code en anglais avec un commentaire (probablement juste pour nous habituer à comprendre ce que fait réellement le code, plutôt que de copier / coller quelque chose et d'espérer le meilleur).

Personnellement, je pense que l'encombrement de votre code l'encombre, le rendant moins lisible que s'il ne s'agissait que de commentaires ou de code. Je suis un codeur C # et les seuls commentaires que je fais tout le temps sont les blocs de commentaires "triple barre oblique" qui sont interprétés en retour dans la documentation IntelliSense. Si je me sens particulièrement coupable d'une façon particulière de faire quelque chose, ou si cela semble particulièrement cryptique, je donnerai une explication supplémentaire, mais c'est à peu près tout.

IMO: Le code auto-documenté est un code dans lequel les noms de variables et de méthodes reçoivent des noms significatifs et contextuels, afin qu'ils décrivent leur objectif.


0

Si vous avez revu votre code plusieurs fois et que vous n'avez toujours pas trouvé de moyen de faire clairement connaître l'intention à quelqu'un qui connaît le domaine. Réécrivez la fonction. Après tout, ce n'est pas plus de 10-20 lignes. S'il est plus long de réécrire la fonction, c'est trop long et c'est en partie pourquoi elle est illisible :) rinse-repeat

et dans le cas peu probable, on ne sait toujours pas ce que fait le code et vous avez pensé à demander de l'aide à vos pairs. Eh bien, nous vous remercions tous d'avoir aidé Linux à évoluer car c'est le code du noyau que vous écrivez, n'est-ce pas? sinon rincez-répétez par le haut :)

Autrement dit, n'écrivez pas, vous commentez les coder


0

Consultez Code Complete 2nd edition, p. 128-129.

Les types de données abstraits vous sauveront de cette énigme. Le code d'auto-documentation est la voie à suivre. Les commentaires peuvent être utiles, mais

des entités du monde réel plutôt que des implémentations de bas niveau

vous pouvez éviter d'utiliser des commentaires.

Une chose à propos des commentaires est que vous les écrivez une fois, mais vous ne les voyez pas lorsque vous implémentez la fonction, vous ne les voyez que lorsque vous modifiez la fonction.

Les commentaires sont vraiment utiles lorsqu'ils sont interprétés par l'EDI comme Delphi 2009+ ou JavaDoc fonctionne, mais c'est plus un langage de balisage structuré, donc dans un sens, vous programmez votre documentation, ce qui est très intelligent.


0

Je crois dans le mantra que le code ne se documente pas lui-même, car vous pourriez être le meilleur programmeur du monde (Ada), et pourtant vous ne comprenez rien à ce qui se passe, mais si vous documentez pourquoi et dans une courte mesure comment votre code fait ce qu'il fait, vous allez vous aider et aider les autres à l'avenir.


0

Les commentaires sont indispensables. Parce que lorsque vous écrivez du code, vous écrivez pour vos besoins actuels, mais aussi pour les personnes à l'avenir qui doivent lire votre code, comprendre wtf, que faites-vous, et pourquoi, puis comment y apporter des modifications.

Si vous gardez cela à l'esprit, lors du codage / programmation?

Comment puis-je faciliter la compréhension et la modification pour les futurs codeurs de ce code sur lequel je travaille, alors vous ferez du bon travail. A défaut, il est difficile pour les autres de modifier votre code, et n'imaginez pas que ce ne sera jamais le cas, c'est rare ...

Dans la plupart de mes tâches, j'ai toujours dû modifier le code des autres, et le plus horriblement écrit, mal documenté.

Donc, votre habitude de penser que le document de code est lui-même n'est pas de faire preuve de diligence raisonnable.

En tant que programmeur, nous devons pratiquer l'autodiscipline qui peut sembler totalement ar aux programmeurs inexpérimentés, mais nous devons avoir des habitudes, pour éviter toutes les expériences horribles que nous avons eues avec le code d'autrui. Ou même en regardant notre propre code des mois, des années plus tard.

Consultez http://thedailywtf.com, ils ont des tonnes d'histoires humoristiques mais réelles sur les programmeurs qui n'ont tout simplement pas fait preuve de diligence raisonnable.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.