Existe-t-il une méthode permettant de différencier les commentaires informatifs du code mis en commentaire?


38

Au cours de la programmation, vous obtiendrez des commentaires expliquant le code et des commentaires supprimant du code:

// A concise description 
const a = Boolean(obj);
//b = false;

Existe-t-il une bonne méthode pour analyser rapidement laquelle est laquelle?

J'ai joué avec l'utilisation de 3 /et /** */de commentaires descriptifs.

J'ai également utilisé un plugin VSCode pour mettre en évidence //TODO:et//FIXME:


2
Comme une note, ///et les /** ... */commentaires sont également utilisés par des générateurs de documentation, tels que Doxygen ou JSDoc. Si vous les utilisez ou utilisez des outils similaires, vous ne pourrez peut-être pas utiliser ce type de commentaire pour des commentaires descriptifs qui ne font pas partie de la documentation.
Justin Time 2 Réintégrer Monica le

1
En javascript, la plupart des lignes de code se termineront probablement par un point-virgule. À moins que vos commentaires ne le fassent, cela semble assez simple et vous pouvez écrire un script pour vérifier cela aussi facilement;
Artemis Fowl le

Réponses:


189

Il existe une solution très simple à cela: supprimez le code commenté.

En réalité, il n'y a que deux bonnes raisons de commenter le code: tester quelque chose / faire une correction ou enregistrer le code que vous utiliserez peut-être plus tard. Si vous testez ou corrigez quelque chose, supprimez le code mis en commentaire dès que vous avez terminé le test ou le correctif. Si vous enregistrez du code que vous utiliserez peut-être plus tard, faites-en un code de première classe et placez-le à un endroit tel qu'une bibliothèque où il peut être utilisé à bon escient.


108
En outre, si le code a été archivé, supprimez-le simplement. Si jamais vous avez besoin de le récupérer, le contrôle de source vous a couvert
mars

38
Lorsque le code est supprimé, personne ne remarque qu'il a jamais existé. Cela rend plus difficile à récupérer. Il est utile de laisser du code commenté, en particulier s'il semble probable qu'il sera utilisé à l'avenir.
usr

76
@usr: Lorsque le code est supprimé, personne ne remarque qu'il a jamais existé - et selon mon expérience, dans 99% des cas réels, c'est la bonne chose à faire. Dans 1%, il peut y avoir une certaine valeur dans les lignes supprimées, cependant, si le code commenté reste dans le magasin pendant plusieurs semaines ou plusieurs mois (ou plus longtemps), il y a de fortes chances qu'il ne soit plus compilé du fait de la refactorisation du code actif. lignes de code. L'argument de la «valeur pontentielle pour les utilisations futures» est souvent utilisé comme une excuse erronée par les personnes qui ont un problème émotionnel consistant à supprimer des éléments de la base de code pour laquelle ils ont investi quelques heures de réflexion.
Doc Brown le

21
Je ne commets jamais de code commenté sans commentaires explicatifs supplémentaires. Il est rare que vous souhaitiez récupérer le code à court terme, mais chacun d'entre eux est exceptionnel et nécessite une explication pour les futurs développeurs (ou pour vous-même). 90% de mes commentaires sont "Supprimés car ils semblent ne pas être utilisés. Supprimez-les après novembre 2021 s'il n'y a pas de problèmes"
James Beninger

31
Mon collègue a un jour déclaré "Il y avait du code ici qui avait X mais je l'ai supprimé" lorsque nous avons supprimé certaines fonctionnalités pour le moment. Cela a vraiment bien fonctionné. vous saviez que ce fichier figurait dans l'historique des sources, mais cela ne vous dérangeait pas.
Erik

45

En ajoutant à l'excellente réponse de @ RobertHarvey, je crois qu'il n'y a qu'une seule raison légitime que j'ai jamais rencontrée pour enregistrer le code commenté dans le contrôle de source, même temporairement: en cas de code de remplacement non évident qui ne devrait pas ou ne pourrait pas être utilisé pour une raison quelconque . Même dans ce cas, la plupart des commentaires devraient être l' explication, pas le code de remplacement. Cela pourrait être un bogue ou une fonctionnalité du langage qui n’est pas encore considérée comme stable. Cela pourrait ressembler à quelque chose comme ça:

# TODO: Replace with `foo = frobnicate(bar)` once <link.to/bug> is fixed
foo = [some complex workaround]

Dans ce cas, le travail a déjà été effectué, mais vous ne pouvez pas encore en tirer parti. Si vous le supprimez, cela signifie que quelqu'un devra le redécouvrir plus tard. Il en va de même pour les solutions sous-optimales qui peuvent sembler supérieures à première vue ou pour des compromis délibérés avec des solutions similaires .

Attention: Ne laissez pas votre code avec des solutions alternatives. Chaque tâche peut être accomplie de multiples façons et il n’est pas rentable d’explorer cet espace pendant longtemps, à chaque changement. Les revues de code peuvent être un bon endroit pour découvrir ces commentaires manquants, lorsque votre collègue suggère une amélioration que vous avez déjà découverte sous-optimale.


2
Le revers de la médaille, c’est que vous devez parfois expliquer pourquoi vous n’utilisez pas frobnicate(bar), pour que personne ne vienne essayer de «réparer» votre code «inélégant». Donc, vous leur montrez que vous savez que dans un monde parfait, la frobnicatefonction serait la voie à suivre, mais vous savez par expérience douloureuse que cela ne fonctionne pas correctement. On ne peut pas s'attendre à ce que le tiers considère cela comme un bogue, encore moins digne d'être corrigé; vous devez toujours laisser un commentaire aux futurs programmeurs (y compris vous-même) sur les raisons pour lesquelles vous n'avez pas adopté l'approche évidente.
Monty Harder le

3
Une situation connexe est qu’il peut exister deux façons de procéder: l’une traitera des données valides beaucoup plus rapidement que l’autre, et l’une offrira des diagnostics plus utiles si, pour une raison quelconque, elle reçoit des données invalides. Si le programme fait partie d'un processus qui ne doit lui fournir que des données dont la "garantie" est valide, mais que quelque chose dans le processus ne fonctionne pas correctement, le fait de disposer d'une version plus lente, mais offrant de meilleurs diagnostics, peut beaucoup plus facile de déterminer ce qui ne va pas.
Supercat

20

Hmm, j'ai lu cette question légèrement différemment de Robert qui affirme correctement que le code mis en commentaire doit être supprimé.

Si, toutefois, vous recherchez une convention pour marquer le code en vue de son retrait ultérieur, l'un de mes favoris est le suivant:

//b = false; //TODO: remove

Certains drapeaux de l'EDI //TODO:peuvent être commentés ou commentés. Sinon, c'est généralement une chaîne interrogeable. Il est préférable de suivre la convention établie par votre boutique, car cela peut se faire de plusieurs manières. Chaque base de code devrait le faire d'une manière. Le maintient consultable.

analyser rapidement lequel est lequel?

Sans cette marque, la méthode automatisée consiste à utiliser le compilateur. Si supprimer le commentaire produit un code compilé, il doit s'agir d'un code commenté. Ecrire un plugin IDE qui vérifie que ce ne serait pas difficile. Mais il laissera du code commenté buggy derrière.

C'est pourquoi il est préférable de simplement marquer le code commenté comme code dès que vous le commentez. Cela vous permet de travailler de manière non destructive pendant que vous décidez si vous le souhaitez vraiment. Puisque nous sommes tous interrompus et oublions quelque peu, ne soyez pas surpris si certaines lignes sont enregistrées alors qu'elles sont dans cet état. S'ils le font, c'est bien qu'ils soient au moins clairement identifiés et consultables. Les macros de clavier m'ont aidé avec cela dans le passé. Il est difficile de s’interrompre au milieu de cela si vous pouvez le faire en appuyant simplement sur une touche.

Vous pouvez aller jusqu’à enchâsser la marque dans vos tests d’intégration continue. Oups, j'essaie de vérifier à nouveau avec les TODO en suspens.


Au lieu de voir si les commentaires sont compilés pour être étiquetés en tant que code, vous pouvez les exécuter via un processeur de langage naturel et étiqueter ceux qui sont analysés sous forme de phrase ou de phrase nominale dans la langue parlée par votre équipe.
TheHansinator

3
@TheHansinator ça sonne bien, mais mon expérience avec la corrélation automatique des téléphones portables avec le jargon de mon codeur me rend prudent.
candied_orange

J'imagine que la PNL utilisée pour analyser les commentaires de code serait bien meilleure que la PNL qui utilise la correction automatique, tout simplement parce que l'ordinateur dispose de la phrase entière et ne tente pas de corriger les fautes d'orthographe. Sans oublier que le faux négatif est également préférable ici: dans la mesure où un humain est capable de réviser le commentaire avant de le supprimer, il peut simplement réécrire le commentaire, au lieu de ne pas être alerté par un gobbledygook inutile.
TheHansinator

3
wrt parsing: double buffer (flip on)-> C prototype ou anglais ultra-concis? ne peut pas dire sans contexte, pas une construction entière correcte dans les deux langues. Certains faux positifs et négatifs sont inévitables lorsque les commentaires, de par leur nature, ne limitent pas la forme de leur contenu dans les deux sens.
Leushenko

8

J'utilise des directives de préprocesseur pour supprimer le code, pas les commentaires du tout:

//comment
active_code();
#if FALSE
inactive_code();
#endif

Cela rend la recherche très facile et mon surligneur de syntaxe le traite comme un commentaire. Je peux même le réduire en une seule ligne:#if FALSE(...)

Vous pouvez développer cette idée pour avoir plusieurs options:

#if OPTION == 0
code_for_option_0();
#elif OPTION == 1
code_for_option_1();
#else
code_for_all_other_options();
#endif

Et vérifier les erreurs au moment de la compilation:

#if FOO >= 5
#error FOO should be less than 5!
#endif

Bien sûr, vous ne voulez pas abuser de cela, ou il devient difficile de dire ce qui est en train d'être compilé et ce qui ne l'est pas. Mais vous avez l’idée, et c’est le même problème que pour le code commenté ... du moment que vous ne l’utilisez que de manière statique. Si vos conditions sont dynamiques, c'est pire.


Pour déterminer lequel est lequel dans une base de code existante qui n'a pas du tout pris en compte ce problème, je ne pense pas qu'il existe une solution universelle. Vous devrez trouver des motifs vous-même et probablement coder une expression régulière pour les trouver.


Pour quoi dans le monde cela serait-il bon? Avez-vous besoin de compiler plusieurs versions?
Tvde1

@ Tvde1 C'est une possibilité et un cauchemar potentiel si vous n'y parvenez pas très bien. Mais l'alternative est peut-être pire. Si vous avez plusieurs copies de presque le même code, une pour chaque variation sur un thème commun, vous devez les conserver séparément et les synchroniser.
AaronD

Il existe plusieurs façons de procéder, mais ils présentent tous une variante du problème de configuration complexe ou du problème de copie indépendante: êtes-vous sûr qu'un correctif a été appliqué à toutes les copies indépendantes? Et si ce n'est pas le cas, et qu'une autre fonctionnalité est ajoutée, elle est alors cassée par le correctif connu avant la fonctionnalité mais non porté jusqu'à présent?
AaronD

3
Cela ne fonctionne que si vous avez une étape de prétraitement comme C. La question est à propos javascript. Vous pouvez effectuer certains pré-traitements, mais cela étendra les capacités du système de compilation et le rendra non standard. Si vous n'avez pas de système de compilation ou si le système de génération ne prend pas en charge l'analyse et l'exécution de code, vous ne pourrez pas implémenter cette solution. Enfin, il ne répond même pas à la question: le code mis en commentaire n'est pas strictement équivalent au code activé de manière conditionnelle. Il peut s'agir d'un reste qui n'est pas censé être activé.
VLAZ

L'activation conditionnelle n'est qu'une extension de la réponse et non la réponse elle-même. Sinon, je l'éditerais pour inclure les commentaires qui l'étendent encore plus.
AaronD

4

Je suis d’accord avec la réponse selon laquelle l’ancien code devrait être supprimé plutôt que commenté, dans la mesure du possible, mais j’ai observé une convention pour les rares occasions où un code commenté est nécessaire.

(Ma base est C # mais ceci peut être appliqué à n’importe quel langage C-syntaxique, par exemple java)

// An explanatory comment has a space between the comment marker and the content.

// The following lines are commented out code so do not have the space (except where indented).
//var a = something();
//if(a==2) {
//   doSomethingElse();
//}

2
Cela dépend totalement du style: lorsque je commente du code, j’ajoute généralement le //à la première colonne et, comme tout le code est indenté en retrait, le commentaire commence pratiquement toujours par le fait que le commentaire commence par quelques onglets. Les commentaires normaux ne reçoivent pas d’espace principal de moi, à moins qu’il n’y ait déjà d’autres commentaires comportant un espace principal à proximité. Ainsi, votre méthode échouerait de manière démesurée sur les commentaires que je produirais, et toute méthode conçue pour reconnaître mes motifs de commentaires échouerait de manière démesurée sur les vôtres.
cmaster

@ cmaster Ah je vois, je pense avoir mal compris la question. J'ai fourni un moyen simple de formater les commentaires de manière à ce qu'ils puissent être facilement analysés en fonction du type, ce qui n'est pas ce qui était demandé.
IanF1

2

J'interprète toujours la question différemment, pensant que vous voulez trouver du code commenté.

Le code de style C doit contenir des points-virgules, alors qu'il est peu probable que les commentaires contiennent des points-virgules. Donc, pour le code commenté d'une seule ligne, vous pouvez utiliser cette expression régulière:

\s*\/\/[\s\S]*;

Pour le code commenté sur plusieurs lignes, il pourrait être

\/\*[^\;]*;[^\;]*\*\/

Remarque Visual Studio est un peu curieux à propos des sauts de ligne dans les expressions régulières; ils ne comptent pas comme des espaces, vous devez spécifier un \ n explicite.


2

Si vous utilisez un éditeur avec un compilateur exécuté en arrière-plan (comme Xcode et Clang), vous pouvez simplement essayer de compiler le texte du commentaire. Par exemple, "une description concise" donne des erreurs, "b = false;" non. Vous pouvez ensuite utiliser une coloration syntaxique différente.

Une méthode plus simple consisterait en un plugin IDE utilisant certaines méthodes heuristiques, comme plusieurs mots d'une ligne autres que les mots clés pointant vers des commentaires, des points assortis pointant en accolade au code, etc.


1

D'autres réponses ont couvert des variantes du thème "Ne commentez pas le code". Mais parfois, vous le voulez toujours pour référence.

Si vous avez réellement besoin du code pour rester, une meilleure solution consiste à entourer le code avec "#if 0 ... #endif", idéalement avec un commentaire indiquant pourquoi. Telle est la stratégie recommandée par diverses normes de codage, y compris MISRA.


-3

Simple, du moins pour moi - et en C / C ++. Les commentaires entre / * * / sont informatifs. Le code de test temporairement supprimé est commenté avec //.

Et il y a de bonnes raisons de laisser le code de test dans le fichier, mais commenté, au moins dans le genre de travail que je fais. Tôt ou tard, quelqu'un voudra qu'une modification soit apportée, ce qui nécessitera ce code. Annuler un commentaire sur un bloc prend une commande de l'éditeur, tout comme le commenter à nouveau lorsque vous avez terminé.


Il y a aussi #ifdef __DEBUG ... #endif, ou n'importe quelle définition personnalisée que vous voulez utiliser. __DEBUGC'est bien, car il suffit souvent de changer la configuration du projet pour l'obtenir. Mais la plupart des IDE vous permettent également de définir vos propres configurations, ce qui peut vous donner n'importe quoi à cet endroit.
AaronD

Qu'entendez-vous par «code de test»? Tests unitaires? Ceux-ci ne doivent pas du tout être commentés, mais conservés dans la suite de tests et exécutés aussi souvent que possible, que quelqu'un le juge nécessaire ou non. Bien sûr, il est facile de redéfinir le commentaire d'un morceau de code, mais c'est encore plus simple de ne rien faire du tout et d'avoir déjà la suite de tests en place ...
leftaroundabout

1
Argh, ne fais pas ça. Commenter le code "pour tester quelque chose" fonctionnera parfaitement 99 fois sur 100 ... et dans un seul cas, vous oublierez de le supprimer (s'il n'est plus nécessaire) ou, pire encore, oubliez de le décommenter ( si cela est nécessaire) et les choses peuvent devenir laides.
CharonX le

@leftaroundabout: Non, je veux dire des choses comme des déclarations printf mises en place pour vérifier les valeurs.
jamesqf

@ jamesqf vous ne devriez jamais avoir besoin de ce genre de choses, c'est pour cela qu'un débogueur est là. Mais même si vous utilisez printf/ coutou un logiciel similaire pour corriger le code nouvellement écrit (ce que je reconnais avoir fait moi-même par le passé), il n'est vraiment pas très efficace de le laisser ici. Si quelqu'un veut faire des changements et sait quelles sont les variables pour lesquelles il a besoin d'informations, il est facile et rapide de l'écrire à printfnouveau, alors que si ce dev ne sait pas ce qui est nécessaire et ne fait pas commenter toutes ces printfdéclarations, l'énorme bande de texte le terminal ne les aidera probablement pas non plus.
gauche vers le
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.