Existe-t-il une méthode pour différencier les commentaires informatifs du code commenté?
Tout au long de la programmation, vous vous retrouverez avec quelques commentaires qui expliquent le code et certains commentaires qui suppriment le 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 3 /'le sable /** */ pour des commentaires descriptifs.
J'ai également utilisé un plugin VSCode pour mettre en évidence //TODO: et //FIXME:
Il existe une solution très simple à cela: supprimer le code commenté.
Vraiment, il n'y a que deux bonnes raisons de commenter le code: pour tester quelque chose/faire un correctif, ou pour enregistrer le code que vous pourriez utiliser plus tard. Si vous testez ou corrigez quelque chose, supprimez le code commenté dès que vous avez terminé le test ou le correctif. Si vous enregistrez du code que vous pourriez utiliser plus tard, faites-en un code de première classe et mettez-le quelque part, comme une bibliothèque, où il peut être utilisé à bon escient.
Ajout à @ 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 code source, même temporairement: en cas de non -code de remplacement évident qui ne devrait pas ou ne peut pas être utilisé en ce moment pour une raison quelconque. Même alors, la plupart du commentaire devrait être le explication, pas le code de remplacement . Cela pourrait être un bug ou une fonctionnalité du langage qui n'est pas encore considéré comme stable. Cela pourrait ressembler à ceci:
# 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 profiter, donc la supprimer signifie que quelqu'un devra le redécouvrir plus tard. Il en va de même pour solutions sous-optimales qui peuvent sembler supérieures à première vue ou compromis conscients contre des solutions similaires .
Attention: ne jetez pas votre code avec des solutions alternatives. Chaque tâche peut être effectuée de nombreuses façons différentes, et il n'est pas rentable d'explorer cet espace pendant longtemps pour chaque changement. Les révisions de code peuvent être un bon endroit pour découvrir de tels commentaires manquants, lorsque votre collègue suggère une amélioration que vous avez déjà découverte comme étant sous-optimale.
Hmm, j'ai lu cette question légèrement différemment de Robert qui affirme correctement que le code commenté doit être supprimé.
Si, cependant, vous cherchez une convention pour marquer le code pour une suppression ultérieure, un de mes vieux favoris est:
//b = false; //TODO: remove
Le drapeau de certains IDE //TODO: commentaires ou peut être appris à. Sinon, il s'agit généralement d'une chaîne de recherche. 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 doit procéder de cette façon. Le maintient consultable.
analyser rapidement qui est lequel?
Sans cette marque, la manière automatisée de le faire est d'utiliser le compilateur. Si la suppression du commentaire produit du code qui se compile, il doit s'agir de code commenté. Écrire un plugin IDE qui vérifie que ce ne serait pas difficile. Mais cela laissera du code commenté bogué derrière.
C'est pourquoi il est préférable de simplement marquer le code commenté comme code au moment où vous le commentez. Cela vous permet de travailler de manière non destructive pendant que vous décidez si vous voulez vraiment que cela disparaisse. Étant donné que nous sommes tous interrompus et que nous sommes quelque peu oublieux, ne soyez pas surpris si certaines lignes sont enregistrées dans cet état. S'ils le font, c'est bien qu'ils soient au moins clairement marqué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 avec une seule touche.
Vous pouvez aller jusqu'à inscrire la marque dans vos tests d'intégration continue. Oups, j'essaie de vérifier à nouveau avec des TODO exceptionnels.
J'utilise les directives du 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érification des erreurs au moment de la compilation:
#if FOO >= 5
#error FOO should be less than 5!
#endif
Bien sûr, vous ne voulez pas aller trop loin là-dessus, ou il devient difficile de dire ce qui est réellement 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é de toute façon ... tant 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 considéré ce problème, je ne pense pas qu'il existe une solution universelle. Vous devrez trouver des modèles vous-même et probablement coder une expression régulière pour les trouver.
Je suis d'accord avec la réponse indiquant que l'ancien code devrait être supprimé plutôt que commenté dans la mesure du possible, mais j'ai observé une convention pour les quelques occasions où un code commenté est nécessaire.
(Ma base est C # mais cela peut être appliqué à n'importe quel langage de syntaxe C, 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();
//}
J'interprète toujours la question différemment, pensant que vous voulez trouver du code commenté.
Le code de style C contient forcément des points-virgules, alors qu'il est peu probable que le commentaire contienne des points-virgules. Ainsi, pour le code mis en commentaire sur 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 particulier à 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.
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 serait un plugin IDE qui utilise des heuristiques, comme plusieurs mots consécutifs autres que les mots clés pointe vers les commentaires, le point accolade bouclé correspondant au code, etc.
D'autres réponses ont couvert des variations sur le thème "Ne pas commenter le code". Mais parfois, vous le souhaitez toujours pour référence.
Si vous avez vraiment besoin du code pour rester, une meilleure solution consiste à entourer le code de "#if 0 ... #endif", idéalement avec un commentaire pour dire pourquoi. Il s'agit de la stratégie recommandée par diverses normes de codage, notamment MISRA.