Les commentaires sont-ils meilleurs dans les environnements à fort taux de roulement?

Je parlais avec un collègue aujourd'hui. Nous travaillons sur du code pour deux projets différents. Dans mon cas, je suis la seule personne à travailler sur mon code; dans son cas, plusieurs personnes travaillent sur la même base de code, y compris des étudiants coopératifs qui vont et viennent assez régulièrement (entre tous les 8 à 12 mois). Elle a dit qu'elle était libérale avec ses commentaires, les mettant partout. Son raisonnement est que cela l'aide à se rappeler où se trouvent les choses et ce qu'elles font, car une grande partie du code n'a pas été écrit par elle et pourrait être modifiée par quelqu'un d'autre qu'elle. Pendant ce temps, j'essaie de minimiser les commentaires dans mon code, en les mettant uniquement dans des endroits avec une solution de contournement ou un bug non évident. Cependant, j'ai une meilleure compréhension globale de mon code et un contrôle plus direct sur celui-ci.

Mon opinion à cet égard devrait être minimale et le code devrait raconter la majeure partie de l'histoire, mais son raisonnement est également logique. Y a-t-il des défauts dans son raisonnement? Il peut encombrer le code, mais il pourrait finalement être très utile s'il y a beaucoup de gens qui y travaillent à court ou moyen terme.

Les commentaires n'encombrent pas le code.

Et quand ils le font, eh bien, chaque IDE à moitié décent peut cacher / plier les commentaires. Idéalement, l'histoire devrait être racontée par votre code, votre document d'exigences, votre historique de validation et vos tests unitaires, et non par des commentaires. Cependant, des commentaires excessifs ne peuvent que nuire lorsque les commentaires sont concentrés sur le comment et non le pourquoi, mais c'est une discussion différente .

Je pense que vous et votre collègue avez raison, la différence étant, bien sûr, que vous travaillez seul et elle en équipe, qui comprend souvent des développeurs inexpérimentés. Vous n'avez pas tellement une philosophie différente sur les commentaires, mais des exigences très différentes sur la communication de votre code. L'argument "ça m'aide à me souvenir" pourrait également provenir du fait qu'elle traite beaucoup plus de code que vous, et plus important encore, du code produit par différentes personnes, chacune avec ses propres préférences et bizarreries.

À la fin de la journée, les commentaires de code, bien que leurs défauts évidents, sont le moyen le plus simple et le plus rapide de communiquer votre code. Selon la composition et l'organisation de l'équipe, cela pourrait même être le seul moyen qui s'applique au plus petit dénominateur commun. Je me retrouve généralement à suivre votre philosophie de commentaire lorsque vous travaillez seul et à m'adapter à celle de votre collègue lorsque vous travaillez en équipe, surtout s'il s'agit d'une compétence d'équipe déséquilibrée.

Les commentaires prolifiques dans ce type d'environnement couvrent un problème qui devrait être résolu d'une autre manière.

Un code de qualité et lisible ne devrait jamais avoir besoin de commentaires supplémentaires pour expliquer ce qu'il fait. Le seul moment pour commenter, c'est quand vous voulez expliquer pourquoi quelque chose a été fait d'une manière particulière. Et même alors, ces commentaires pourraient sans doute être dans des messages de validation du contrôle de code source.

Ainsi, le problème qu'elle résout est qu'elle doit travailler avec des étudiants qui ne savent pas écrire leur code de manière lisible. À mon avis, encombrer le code de commentaires est une faible solution à ce problème.

Des révisions rigoureuses du code seraient beaucoup plus efficaces, à la fois pour garder le code en ordre et pour améliorer ces étudiants pour l'avenir, que ce soit dans la même entreprise ou ailleurs.

Le problème avec les commentaires est qu'ils ont tendance à se désynchroniser très rapidement avec le code. Cela signifie qu'il y a souvent des commentaires erronés ou trompeurs dans le code, donc ils nuisent plus à la lisibilité qu'ils ne l'aident.

L'objectif est de rendre une base de code facile à comprendre et à modifier. Vous pouvez le faire grâce à une utilisation libérale des commentaires (bien que vous puissiez rencontrer le problème à partir des commentaires de données), ou vous pouvez écrire du code auto-documenté (autant que possible), et utiliser uniquement des commentaires pour expliquer le non pourquoi "pourquoi" " des questions. L'une ou l'autre approche peut fonctionner, mais gardez en moi que pour modifier le code, vous devrez comprendre le code lui-même, et pas seulement les commentaires. Ainsi, bien que les commentaires puissent vous aider à comprendre le code, à la fin de la journée, vous devrez probablement comprendre le code lui-même. Cela dit, je préfère l'approche du code auto-documenté. Cela semble être un moyen plus direct de créer une base de code propre.

"Est-ce que plus de commentaires sont meilleurs dans les environnements à fort taux de roulement?"

Je pense qu'ils pourraient bien être pires:

• Différents auteurs utiliseront différents styles et niveaux de détails et seront moins enclins à mettre à jour les commentaires d'autres personnes.

• L'opinion de «ce qui doit être commenté» change d'une personne à l'autre.

• Ils continuent la pratique d'écrire du code difficile à lire avec des commentaires pour l'expliquer, par opposition au code facile à lire avec des noms descriptifs.

• Le maintien de leur format et de leur cohérence devient un travail en soi.

• Les nouveaux utilisateurs doivent apprendre la norme «format» avant de pouvoir effectuer des changements rapides.

Point 1: la clarté est importante dans les environnements à forte rotation

Point 2: la verbosité n'est pas la clarté

L'ajout de commentaires à votre code peut ou non améliorer la clarté; cela dépend des commentaires que vous ajoutez. Et une fois que la clarté optimale est atteinte, des commentaires supplémentaires aggraveront la situation, pas la améliorer.

Bien que les commentaires soient un élément de clarté, la qualité du code est un élément beaucoup plus important. L'astuce est l'opposé de la clarté . Si la fonction du code n'est pas immédiatement apparente lors d'une lecture occasionnelle, alors le code n'est pas particulièrement clair et les commentaires (quelle que soit la qualité des commentaires) sont un substitut médiocre et inefficace pour un code clair.

Par exemple, le bourrage d'un indicateur dans le bit haut d'un champ non lié peut être parfaitement autorisé dans certaines circonstances, et cela peut avoir beaucoup de sens du point de vue des performances dans certaines circonstances, mais c'est à peu près toujours une mauvaise idée en ce qui concerne la clarté , même si vous commentez l'enfer.

Si vous devez expliquer en prose ce que fait votre code, envisagez l'une des actions suivantes: Notez que certaines d'entre elles peuvent affecter les performances, mais les performances peuvent ne pas être aussi importantes que la clarté dans certains cas.

• Meilleurs noms de variables et noms de fonctions
• Meilleure disposition et espacement du code
• Supprimez tous les "trucs" que vous pensiez être une bonne idée
• Regroupez le code en fonction de la fonction conceptuelle (par exemple, extrayez le code dans un but spécifique dans une fonction correctement nommée, même si vous ne l'appelez qu'une seule fois)
• Utilisez un algorithme plus simple (si les conditions le permettent)
• Utilisez des bibliothèques bien connues pour des fonctionnalités communes

Une réponse simpliste: "Plus votre code est susceptible d'être relu, plus il vous sera difficile d'expliquer ce que vous faites." Cela pourrait être en rendant le code plus facile à lire, en commentant ce, en créant des documents officiels, en suivant les normes de style ... S'il vous plaît noter que ce pourrait être vous qui fait le relisant plus tard, mais il est certainement vrai aussi des autres dans un environnement de roulement élevé.

Il y a un autre grand fil qui couvre si les commentaires sont ou non de la documentation.

Les commentaires sont plus utiles dans certains scénarios que dans d'autres. C'est tellement fondamental que je m'inquiète de savoir comment l'expliquer au milieu de tant de réponses que je perçois comme "anti-commentaire".

Si votre code peut ne pas être lu pendant des années, les commentaires sont plus importants que si vous avez une refactorisation fréquente du code, une forte propriété du code et de nombreuses révisions du code. Si votre application est complexe et utilise des techniques qui ne sont pas immédiatement évidentes pour un observateur compétent dans cette langue, les commentaires sont plus importants que si le système est un "Hello World" glorifié. Si la base de code n'est pas aussi stricte avec les normes qu'elle pourrait l'être, les commentaires sont plus importants que si vous travaillez avec six couches d'AQ. Si vous travaillez dans une équipe de huit personnes qui apprennent la langue, les commentaires sont plus importants que si votre équipe a huit programmeurs Pulitzers. Si vous avez une application tentaculaire sur vos genoux,les commentaires sont plus importants que si vous pouviez le construire à partir de zéro.

Serait-il préférable dans la plupart de ces scénarios de corriger la cause sous-jacente au lieu d'augmenter l'utilisation des commentaires? Absolument. Mais parfois, vous êtes coincé avec une base de code qui a plus d'empreintes digitales que le smartphone de la ville, et la meilleure façon de l'améliorer est de rendre vos modifications aussi lisibles que possible et de commenter le diable.

À votre problème spécifique: les commentaires ne devraient pas être éparpillés au point d'encombrer le code. Un paragraphe bien écrit en haut d'un sous-programme, décrivant pourquoi une fonction existe et peut-être pourquoi elle utilise cette approche, est souvent le meilleur pari pour aider le prochain programmeur à se repérer.