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

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:

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.

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.

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.

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.

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();
//}

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.

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.

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.

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é.