Quel est le ratio code d'or / commentaire? [fermé]

https://stackoverflow.com/questions/111563

02-07-2019
|

Question

Existe-t-il un rapport code / commentaire que vous considérez comme un signe de bonne (mauvaise) santé du code?

Pouvez-vous donner des exemples de projets open source considérés comme bien codés et leur taux de commentaires respectif?

(Je réalise qu’aucun rapport n’est "vrai" pour chaque projet et il se peut très bien que des projets merdiques affichent ce nombre d’or théorique. Encore ...)

La solution

Les commentaires doivent être très rares et précieux, exprimant presque toujours le "pourquoi". et jamais le " comment " (à l'exception des cas où le comment est complexe et difficile à distinguer du code).

Chaque commentaire est un indice qu'il vous faudra peut-être refactoriser pour clarifier l'intention du code. Chaque commentaire risque de devenir périmé dès sa rédaction.

Dans notre projet xUnit.net , il n'y a presque pas de commentaires XML, mais certaines personnes semblent trouver le code clair et facile à lire. :)

Autres conseils

Quiconque doit corriger le code d'un autre programmeur dit autant de commentaires que possible . Le gros problème avec l'ancien code est le suivant: "Vous voyez ce que le code fait. Vous voyez que c'est le problème. Mais vous ne savez pas pourquoi le programmeur l’a écrit ainsi. "

Pour comprendre un bug, vous devez savoir:

que devrait faire le code (et non ce que fait le code) et pourquoi.
Le contrat de chaque fonction. Par exemple, s'il existe une exception NullPointerException, où se trouve le bogue? Dans la fonction ou dans la fonction appelante?
Sur chaque piratage, il est décrit comment le problème peut être reproduit (version linguistique, système d'exploitation, version du système d'exploitation). Par exemple, nous avons beaucoup de hacks pour une ancienne machine virtuelle Java qui n'est plus supportée. Mais nous ne savons pas si nous pouvons le supprimer car nous ne savons pas comment les reproduire.

Nous avons un ratio de 2-3%, ce qui est trop peu. Je pense que 10% est bon pour les projets de grande ou de longue durée.

Désolé, il n'y a pas de règle générale. Les frameworks et les bibliothèques, par exemple, nécessitent beaucoup plus de commentaires, car les programmeurs sont des clients et n’ont pas le temps de lire le code chaque fois qu’ils ont besoin d’appeler une méthode.

Les projets dans lesquels vous écrivez / lisez du code nécessitent moins de commentaires et doivent essayer d’améliorer la lisibilité du code au lieu du ratio commentaire / code.

Cordialement

Les commentaires ne font pas qu'expliquer le code, ils guident également le débogueur qui recherche le code qui fait quelque chose.

Récupérer l'historique des commandes d'un client ou déterminer si un joueur ennemi est visible peut prendre des dizaines de lignes de code. Même un programmeur expert peut prendre plusieurs minutes pour s'assurer que c'est bien ce qu'il fait. Un commentaire indiquant "Récupérer l'historique des commandes du client". permet au débogueur de ne pas étudier ce code du tout, s'il sait que l'historique des commandes n'est pas le problème.

Je commente tout ce qui, à mon avis, est ambigu ou devrait être expliqué. Souvent, je commente. Pourquoi? Parce que vous ne savez jamais qui travaillera sur votre code. J'aime imaginer une situation où ils remplacent la moitié de l'équipe par des singes qui comprennent seulement que lorsqu'ils appuient sur une ligne, ils obtiennent une banane. Donc, s'ils apprennent au moins à lire, ils ne changeront pas ma logique sans lire les commentaires au préalable.

Cas et point:

// Delete the helloworld file
exec("rm -f helloworld.txt")

Ne sera pas remplacé par:

exec("rm -rf /")

Peu probable, je le sais, mais même certains bons développeurs sont connus pour changer de logique parce que cela ne semble pas correct et non pas à cause d'un bogue ou d'un changement d'exigence. .

Je pense que tout le monde peut convenir que 0 commentaire peut généralement être considéré comme un code sous-documenté. N'oubliez pas que même le code le plus auto-documenté ne peut jamais documenter ce qui existe ; jamais ce qui a été intentionnellement laissé de côté, optimisé, essayé et jeté, etc. Vous aurez toujours un peu besoin d'anglais, essentiellement, dans vos fichiers source, ou vous êtes obligé de laisser de côté des mises en garde et décisions de conception importantes.

Je suis intéressé par la façon dont ces principes de son que vous préconisez (avec lesquels je suis tout à fait d'accord jusqu'à présent) se traduisent par des statistiques de code. En particulier, quels projets open source sont considérés comme étant bien (pas trop) documentés, et quel est le ratio de commentaires ici.

J'ai une règle très simple: si vous devez vous arrêter plus de 15 secondes environ pour coder un morceau de code (une fonction ou une boucle complexe, etc.), alors ce morceau de code besoin d'un commentaire.

Cela fonctionne vraiment bien pour moi. La prochaine fois que vous ou quelqu'un de votre niveau de compréhension de la base de code dans son ensemble rencontrez ce code, il (elle) verra immédiatement la raison : comment cela a-t-il été fait.

LOC / LOcomment = yearsofexp / 5

Ma règle est la suivante: s'il y a quelque chose à dire et que le code ne peut pas être exprimé, vous pouvez écrire un commentaire. Sinon, si le code peut exprimer l'idée, vous devez l'exprimer dans le code ou dans ses tests.

Si vous suivez cette règle, votre code ne devrait nécessiter de commentaires que s'il traite d'un problème non évident au niveau du matériel ou du système d'exploitation, ou lorsque l'algorithme le plus évident n'est pas le meilleur choix. Ce sont "c’est bizarre parce que" La plupart du temps, les commentaires dans le code ne sont que des excuses pour ne pas l'avoir écrit de manière plus évidente. De tels commentaires devraient être supprimés, puis supprimés.

Même les bons commentaires deviennent souvent des mensonges au fil du temps, de sorte que les informations se trouvant dans des endroits non exécutables et non testables, comme les commentaires, doivent être surveillées avec suspicion. Encore une fois, la réponse est d’abord d’éviter le commentaire, puis de le supprimer.

Mon ratio idéal est zéro. Cependant, le monde n’est pas idéal, j’accepte donc les commentaires quand il n’ya pas d’autre moyen de communiquer une idée importante.

Il devrait y avoir des commentaires là où vous les jugez nécessaires. Ni plus ni moins.

Lorsque vous regardez à nouveau le code, commentez les parties que vous ne comprenez peut-être pas après plus de 6 semaines de pause

J'essaie de garder les commentaires au minimum. Le code doit être auto-explicatif et bien que le code source ait tendance à changer, les commentaires restent presque toujours en arrière comme explication erronée.

Le ratio code d'or / commentaire est l'intersection de

commentaires nécessaires pour vous rappeler les éléments que vous avez en tête lors du codage
commentaires nécessaires pour rappeler aux autres ce que vous aviez à l'esprit lors du codage
les commentaires que votre client est disposé à payer (car de bons commentaires coûtent du temps)
l’intérêt du développeur pour la production de code obfusqué pour des raisons de sécurité au travail (s’il travaille pour une entreprise où un développeur peut s’en tirer à bon compte)

Cela montre également pourquoi ce rapport est différent pour chaque projet et chaque équipe.

Il n'y a pas de nombre d'or. Le nombre de commentaires dépend grandement de la complexité inhérente du code. Si vous écrivez simplement des applications CRUD, vous n’avez probablement pas besoin de beaucoup de commentaires. Si vous écrivez un système d'exploitation ou un SGBDR, vous aurez probablement besoin d'en commenter davantage, car vous ferez du codage plus compliqué, et vous aurez besoin de rendre un peu plus explicite pourquoi vous faites ce que vous faites. / p>

Si vous souhaitez obtenir des données réelles sur les ratios de commentaire pour différentes langues, consultez Ohloh . / p>

A titre d'exemple, vous pouvez consulter les diverses statistiques pour la Source du noyau Linux.

Je suppose que personne ne peut vous donner de chiffres, mais cela devrait être beaucoup plus élevé dans les fichiers d'en-tête que dans les sources.

Je m'attendrais à ce que le fichier d'en-tête d'une classe documente toutes les classes / fonctions / etc. accessibles publiquement en incluant ce fichier d'en-tête. Cela peut prendre pas mal de lignes pour documenter une fonction dont le prototype est une seule ligne (non, il ne suffit pas de choisir les bons noms pour les fonctions et leurs paramètres - ça peut l'être, mais ce n'est souvent pas le cas). Trois lignes de commentaires pour chaque ligne de code ne seraient pas excessives.

Pour le code actuel, il serait beaucoup plus bas. Je ne suis pas d’accord avec les extrémistes qui pensent que vous devriez viser zéro commentaire, mais si vous pensez avoir besoin de commentaires, vous devez d’abord déterminer si le code pourrait être clarifié.

Cela peut varier un peu. Par exemple, vous pouvez avoir un code si bien écrit que les commentaires ne seraient qu'une perte de temps.

Vous avez besoin de suffisamment de commentaires pour pouvoir consulter votre code, lire le commentaire quelques mois plus tard et reprendre votre travail sans effort. Si l'histoire du code n'est pas obligatoire, ne l'écrivez pas.

Il n’existe pas de bon commentaire sur le code. Auparavant, certaines personnes pensaient qu'il était nécessaire d'avoir un commentaire à la tête de chaque fonction pour expliquer son rôle.

Cependant, avec l’avènement des langues modernes, le code est quasiment auto-documenté. Cela signifie que les seules raisons qui restent pour insérer un commentaire dans le code sont soit d'expliquer d'où vient une décision étrange, soit d'aider à la compréhension d'un sujet vraiment compliqué.

Il n’existe pas de "nombre d’or". Cela dépend de la langue et de la façon dont vous l'écrivez. Plus votre code est expressif, plus il peut être auto-documenté - et donc moins de commentaires sont nécessaires. C'est l'un des avantages des interfaces fluides.

Vous ne pouvez pas imposer un rapport code / commentaires fixe, sans quoi vous finirez avec un code avec du bruit tel que:

// Add one to i
i++;

qui ne fait qu'embrouiller le code.

Observez plutôt la complexité du code et voyez ce que vous devez expliquer, à savoir la logique complexe, pourquoi certains nombres magiques sont utilisés, quelles sont les hypothèses concernant les formats entrants, etc.

Allumez votre état d'esprit des responsables et demandez-vous ce que vous aimeriez voir décrit en ce qui concerne le code que vous venez d'écrire.

HTH.

acclamations,

Rob

Les commentaires ont 3 utilisations, IMO:

Expliquez pourquoi le code fait ce qu'il fait
Documentez l'interface d'un module
Expliquez pourquoi d'autres approches d'une partie de la logique n'ont pas été prises

Si le code fait quelque chose d'assez basique pour que le pourquoi soit clair, ce qui devrait être la plupart du temps dans la plupart des domaines, alors les commentaires dans la logique devraient être minimes ... même s'ils n'en approchent aucun . Les commentaires ne doivent jamais expliquer le quoi (avec des exceptions possibles pour dire, par exemple, que la fonction est une implémentation de l'algorithme Foo, comme expliqué dans Bar Publication). Si vous devez expliquer ce que vous faites, vous le faites mal.

Il existe une excellente discussion sur les commentaires de code dans Steve McConnells () du livre Code Complete (J'ai la première édition, mais je crois qu’elle est maintenant une deuxième édition texte du lien )

En résumé, cela renforce ce que les autres réponses ont dit - devrait être rare et décrire le pourquoi pas - si vous pouvez refactoriser la variable et les noms de méthodes pour remplacer les commentaires, cela devrait être préféré - la plupart des IDE offrant une sorte d’intellisense ( ou comme j'ai déjà entendu Don Box le décrire comme suit: intellicrack en raison de sa dépendance), il n'y a aucune raison de tronquer les noms de variable / méthode lorsqu'une version plus claire en indiquerait plus clairement l'intention

0/0 ; zero divided by zero
Runtime error (func=(main), adr=3): Divide by zero

un implicite "Faites ce que je veux dire" commande avec un " pas de commentaire " commenter?

Il n'y a pas un tel ratio.

Habituellement, les commentaires ne doivent être présents que dans les cas où quelque chose pourrait être vraiment incertain, comme

// Do not Dispose!
SPSite site = properties.Feature.Parent as SPSite;

D'un autre côté, si vous vendez du code à quelqu'un, vous aurez besoin d'autant de commentaires que possible. Imagerie vendant un moteur 3D ou un autre jeu de middleware sans commentaires. Bien sûr, la documentation API, etc. est également une partie importante de ce middleware, mais un bon code commenté est également rentable. Des trucs comme "Ajouter 1 à i" est encore trop spam, mais quelque chose comme "CreateDevice () vérifie d’abord si DirectX 10 est disponible et revient au périphérique DirectX 9 sinon" peut être très utile, même s’il est trivial de voir à partir du code.

Généralement, le code interne est généralement beaucoup moins commenté que le code que vous vendez, mais des exceptions peuvent s'appliquer.

J'aime utiliser les commentaires pour annoter le code qui, à mon sens, est facile à lire et comporte des variables informatives. Cela dit, j'aime bien écrire chaque ligne de code pour être aussi informatif qu'un commentaire, si possible. Vous devriez pouvoir avoir une idée très précise de ce que fait le code avant de lire les commentaires, ou vous le faites mal.

entre 3% et 9,5%, plus ou moins

Je dois dire que je suis venu ici pour chercher une réponse autour de 2 commentaires par 1 ligne de code. Même si c'est une exagération, c'est dans la bonne direction! Au lieu de cela, je vois des gens recommander de traiter des commentaires comme des truffes ou d'autres produits rares. Dans une perspective académique particulière, où la qualité du code est faible et l’utilisation du contrôle de version est encore plus rare que les truffes, j’invite quiconque à écrire autant de commentaires que possible, même à votre avis si ce commentaire est nécessaire à 100%.

Les commentaires vous facilitent la vie car il est probable que vous pensiez à quoi diable je pensais en écrivant cela!

Licencié sous: CC-BY-SA avec attribution

Non affilié à StackOverflow