Le code commenté est-il vraiment toujours mauvais?
Pratiquement tous les textes sur la qualité du code que j'ai lus conviennent que le code commenté est une mauvaise chose. L'exemple habituel est que quelqu'un a changé une ligne de code et y a laissé l'ancienne ligne en commentaire, apparemment pour dérouter les gens qui liront le code plus tard. Bien sûr, c'est une mauvaise chose.
Mais je me retrouve souvent à laisser du code commenté dans une autre situation: j'écris un algorithme de géométrie computationnelle ou de traitement d'image. Pour comprendre ce type de code et y trouver des bogues potentiels, il est souvent très utile d'afficher des résultats intermédiaires (par exemple dessiner un ensemble de points à l'écran ou enregistrer un fichier bitmap). Regarder ces valeurs dans le débogueur signifie généralement regarder un mur de nombres (coordonnées, valeurs de pixels bruts). Pas très utile. Écrire un visualiseur de débogueur à chaque fois serait exagéré. Je ne veux pas laisser le code de visualisation dans le produit final (cela nuit aux performances, et ne fait généralement que confondre l'utilisateur final), mais je ne veux pas non plus le perdre. En C++, je peux utiliser #ifdef pour compiler conditionnellement ce code, mais je ne vois pas beaucoup de différence entre ceci:
/* // Debug Visualization: draw set of found interest points
for (int i=0; i<count; i++)
DrawBox(pts[i].X, pts[i].Y, 5,5);
*/
et ça:
#ifdef DEBUG_VISUALIZATION_DRAW_INTEREST_POINTS
for (int i=0; i<count; i++)
DrawBox(pts[i].X, pts[i].Y, 5,5);
#endif
Donc, la plupart du temps, je laisse le code de visualisation commenté, avec un commentaire disant ce qui est visualisé. Lorsque je lis le code un an plus tard, je suis généralement heureux de pouvoir décommenter le code de visualisation et littéralement "voir ce qui se passe".
Dois-je me sentir mal à ce sujet? Pourquoi? Existe-t-il une solution supérieure?
Mise à jour: S. Lott demande dans un commentaire
Êtes-vous en quelque sorte "sur-généralisant" tout le code commenté pour inclure le débogage ainsi que le code insensé et obsolète? Pourquoi faites-vous cette conclusion trop généralisée?
J'ai récemment lu "Clean Code" de Robert Martins, qui dit:
Peu de pratiques sont aussi odieuses que la mise en commentaire de code. Ne fais pas ça !.
J'ai relu le paragraphe du livre (p. 68), il n'y a aucune qualification, aucune distinction entre les différentes raisons de commenter le code. Je me suis donc demandé si cette règle est trop généralisante (ou si j'ai mal compris le livre) ou si ce que je fais est une mauvaise pratique, pour une raison que je ne savais pas.
L'avantage de # ifdef au lieu de le commenter, c'est que (sur les grands projets), vous pouvez avoir les définitions répertoriées dans un fichier make ou config - et donc ne pas avoir à aller manuellement dans un commentaire, à construire, puis à re -les commenter si c'est dans de nombreux endroits. L'inconvénient est que changer la définition du projet DEFINE signifie généralement reconstruire le tout, pas seulement les fichiers modifiés.
Bien que ... je pense que le "code commenté est une mauvaise chose" se réfère vraiment à code mort que les gens ne voulaient simplement pas supprimer pour une raison quelconque (peur de jeter quelque chose qu'ils ont dépensé) peut-être le temps?). Ce n'est pas vraiment la situation que vous avez pour vous.
S'il est commenté, cela peut pourrir: lorsque vous décidez soudainement que vous en avez à nouveau besoin, vous vous rendez compte qu'il ne se compile plus, ou doit être réécrit pour l'adapter à d'autres choses qui ont changé entre-temps.
Si vous laissez le code dedans, mais de telle manière que le compilateur puisse l'optimiser s'il n'est pas nécessaire, alors vous bénéficiez de garder le code à jour et ne pas avoir à subir le binaire ajouté taille ou performances d'exécution.
Par exemple, en C, cela risque de pourrir:
/*
doSomeDebugStuff();
*/
Et c'est ainsi:
#if 0
doSomeDebugStuff();
#endif
Mais c'est bien, car sa validité est toujours vérifiée par le compilateur, mais susceptible d'être optimisée:
if (0)
{
doSomeDebugStuff();
}
Modifier: comme d'autres le soulignent, utilisez un symbole significatif plutôt que 0 pour le test c'est encore mieux.
// The problem with commented out code is that it can hide what you're actually
// trying to say in a wall of text. Syntax highlighting may help, but you're
// still left with this huge ginormous wall of text in front of you, searching
// through it for what the actual answer is. You'd think that mentally it'd be
// really easy to disregard the comments, but in actual usage, it's a lot harder
// than a one Word answer that can tell you what you're looking for. It's tough.
/* Sometimes they'll even through you off with different comments. */ Yes.
// It's really tough to deal with people that don't like to use source control,
// that would rather comment lines and lines of code instead of deleting the
// code and checking in revision. Cue irrelevant paragraph about the reason why
// I wrote this instead of just deleting the entire block and replacing it
// with my intention. Maybe I was hedging my bets? Cue misspelled wrod.
Je pense qu'une distinction doit être faite entre le code commenté qui est obsolète et le code qui n'est utilisé que dans une version de débogage (ou une autre version "spéciale", conditionnellement compilée). Ce dernier est une pratique courante, et rien ne cloche.
Le premier ne devrait pas être présent dans une base source, car le système de contrôle de version garde une trace des éléments obsolètes, si jamais vous souhaitez les récupérer.
Il n'y a presque pas de "toujours" dans le codage :) Si vous en savez assez sur les raisons d'une directive et que vous avez vraiment de bonnes raisons de la casser, faites-le.
Par exemple, je commente le code quand je fais du "refactoring kamikaze" et j'ai besoin d'un rappel visuel pour ajouter des choses ou me souvenir du fonctionnement de l'ancien code pendant un certain temps. Il est crucial dans des cas comme celui-ci que vous supprimiez les commentaires plus tard, sinon ils encombreront simplement votre code.
Parfois, vous mettez du code dans vos commentaires pour montrer comment utiliser une classe - c'est très différent du code de mise en commentaire qui fonctionnait auparavant.
Je fais beaucoup de revues de code et je trouve qu'il n'y a aucune vraie excuse pour le code commenté quelle que soit la raison. Si vous utilisez le code commenté à des fins de débogage, vous pouvez créer un mécanisme de trace qui est désactivé en mode édition ou qui a des niveaux de trace (toujours bon pour pouvoir tracer dans une version d'édition) ou vous pouvez simplement utiliser un débogueur.
Le code commenté est mauvais parce que lorsque d'autres personnes lisent le code - en particulier lorsque vous êtes stressé d'essayer de corriger un bogue lorsque l'auteur d'origine est en vacances - c'est qu'il est très déroutant de lire le code, surtout si l'erreur provient d'une erreur placé // au début de la ligne ... même en utilisant/* vous pouvez par accident commenter quelque chose qui aurait dû être là - ou pas.
Pour garder votre code propre et plus lisible, supprimez le code commenté, ses programmes sont déjà difficiles à lire car il est sans avoir à lire le code qui peut ou non être significatif.
Oui, ça l'est.
Même si vous avez du code de débogage que vous ne voulez pas dans votre version de production, vous ne devez pas le commenter. En utilisant #ifdef est mieux, car vous pouvez alors activer et désactiver le débogage facilement avec un #define macro, ou en ayant une configuration de build distincte. Cela vaut vraiment la peine de devoir entrer dans le code et de commenter/décommenter chaque bloc du code de débogage manuellement.
Et si vous avez besoin de flexibilité pour activer certains blocs de débogage mais pas d'autres, vous devez alors regrouper les blocs de débogage en "niveaux de débogage".
Une meilleure solution serait de ne pas utiliser du tout le préprocesseur et d'utiliser des fonctionnalités en langage natif, comme les constantes et les instructions if. Donc au lieu de
#define DEBUG0
#ifdef DEBUG0
// debugging code
#endif
vous pouvez avoir
const bool DEBUG0 = true;
if(DEBUG0)
{
// debugging code
}
L'avantage de faire cela, par rapport à l'utilisation du pré-processeur, est que votre code de débogage sera toujours vérifié par le compilateur. Cela diminue la probabilité qu'il pourrisse lorsque vous modifiez le code qui l'entoure.
Vous ne subiriez aucun impact sur les performances si vous faussiez le drapeau booléen, car les compilateurs modernes optimisent le code inaccessible. Au pire, vous pourriez recevoir un avertissement du compilateur à ce sujet.
Je ne pense pas que ce que vous faites est mauvais, mais je pense qu'au moins vous devriez avoir quelques commentaires réels pour expliquer ce qu'il fait, pourquoi, comment et quand utiliser il.
Personnellement, je mettrais normalement ce genre de chose dans une sorte d'effort de type IF DebugMode = TRUE autour du code en question et le définirais comme paramètre de ligne de commande/démarrage. Pour moi, cela permet de voir plus facilement que c'est pourquoi le code est là et comment le définir, bien que dans votre cas, il puisse y avoir des problèmes de performances avec cette petite comparaison que vous souhaitez éviter.
Donc, je verrais probablement ce que vous faites comme un mal nécessaire plutôt que comme un mal. Si vous pouvez trouver un moyen de le rationaliser, faites-le de toute évidence, mais je ne vous en voudrai pas.
Je pense que l'une des raisons pour lesquelles le code a été commenté est considérée comme une odeur de code, c'est qu'il indique soit que le programmeur qui l'a mis là ne comprend pas son contrôle de code source, soit qu'il n'en utilise aucun. Chacun de ces éléments jette encore plus de doutes sur beaucoup d'autres choses qu'ils font également.
Si vous avez une raison légitime pour cela et vous laissez une explication pour laquelle c'est une raison légitime où il peut être trouvé que vous allez probablement bien. La plupart des choses qui sont généralement considérées comme de mauvaises nouvelles peuvent également être un outil utile entre de bonnes mains. Le problème est que ces mains sont plus rares que les gens qui pensent les avoir.
Il aide à fournir un historique de la façon dont l'esprit des programmeurs fonctionnait à l'époque. Mais en ces jours de contrôle de source omniprésent, il n'y a aucune raison de le laisser dans une version définitive - les versions précédentes contiendront l'ancien code si vous avez besoin de vous y référer.
Je ne pense pas qu'il y ait des absolus ici. Je laisse parfois du code commenté quand ce n'est qu'un petit extrait, surtout s'il y a une chance raisonnable que je le décommente bientôt. En gros, je laisse ces extraits tant qu'ils ne perturbent pas la lisibilité du code réel, et tant qu'ils ne se multiplient pas partout.
Ce que je rejette absolument, ce sont les méthodes complètes de mise en commentaire du code. Oui, je les ai déjà vus: WTF. Ils peuvent se reposer dans le paradis de la révision des sources ;-)