Pourquoi est-il mal de commenter le code, puis de le supprimer progressivement pour garder une trace de ce que j'ai déjà fait et de ce qui reste à faire?
Chaque fois que je découvre qu'une grande partie de mon code doit être modifiée, soit parce qu'elle est incorrecte, soit parce qu'elle doit être adaptée aux changements architecturaux majeurs nécessités par d'autres raisons, voici ce que je fais généralement:
- Je commente tout le code que je soupçonne de devoir changer. Je traite le code commenté comme une sorte de ma liste TODO.
- Je passe progressivement en revue le code commenté et décommente les parties de ce code, ou les copie-colle ailleurs et les modifie si nécessaire, ou réécris des parties de ce code à partir de zéro, en regardant le code commenté pour référence. Chaque fois que je pense avoir terminé avec une partie du code commenté, je le supprime.
- Je continue jusqu'à ce que je ne voie plus de code commenté.
Je dois noter que je le fais en grande partie sur le projet personnel que je développe seul.
Cependant, on m'a dit que je devais arrêter de faire ça. On m'a dit qu'à la place, je devrais commencer à utiliser git, en faisant référence aux anciens commits pour voir l'ancien code, au lieu de laisser le code commenté. On m'a dit:
Commenter le code est une mauvaise habitude qui devrait être effacée. Vous manquez d'expérience donc vous ne comprenez pas cela. Si, dans quelques années, vous voyez le code d'une autre personne qui aime commenter le code, vous commencerez vous-même à jurer sur cette personne. Chaque fois que je vois du code commenté, je le supprime dans son intégralité, sans même le regarder, car généralement un tel code n'a aucune valeur. Vous ne verrez certainement pas les inconvénients de commenter le code dans de petits projets d'une personne; mais si vous trouvez un travail et que vous gardez cette habitude là, ce sera dommage.
Puis-je demander quels sont ces inconvénients de ce que je fais que je ne vois pas maintenant?
Je dois dire que je n'ai pas vraiment envie de n'utiliser que git pour voir le code passé. Comme je l'ai dit, je traite les commentaires du code comme une sorte de liste de tâches; alors que git me montrera à quoi ressemblait le code, il ne me montrera pas clairement quelles parties du code doivent encore être examinées et lesquelles sont déjà effectuées. Je crains de manquer une partie du code et d'introduire des bogues.
Pour être complet, je pense que je devrais ajouter que la personne que je cite est un développeur expérimenté et un fan du "Clean Code" d'oncle Bob - et oncle Bob a critiqué commenter le code durement dans son livre.
Si vous supprimez finalement tout le code commenté, je ne vois aucun problème réel avec cela. Laisser du code commenté dans votre base de code est une mauvaise pratique, mais ce n'est pas ce que vous faites si vous travaillez sur tout cela et que vous l'éliminez. Je soupçonne que la personne à qui vous parlez ne comprend pas le processus que vous utilisez ou est dogmatique.
En réalité, le code commenté est inoffensif. Le problème est que c'est désordonné et qu'il est difficile à lire. Il y a des péchés bien pires mais c'est une chose très simple à éliminer. En tant que personne qui a commenté le code, vous êtes le mieux placé pour déterminer qu'il peut être complètement supprimé.
De nombreux IDE et éditeurs de code comprennent une sorte de syntaxe "TODO" dans les commentaires. Il s'agit d'une autre manière de marquer ce qui doit être changé. Vous voudrez peut-être considérer cela car il donne un peu plus d'informations sur ce que vous pensiez lorsque vous l'avez marqué.
À la fin de la journée, faites les choses de la manière qui vous donnera le meilleur résultat. Même s'il s'agissait d'un projet d'équipe, tant que vous supprimez tout le code commenté, vous ne chargez personne d'autre.
Puis-je demander quels sont ces inconvénients de ce que je fais que je ne vois pas maintenant?
Sans doute, si vous travaillez seul et que vous n'utilisez pas le contrôle de version et que vous pensez que vous pouvez le faire de cette façon.
En fait, sans contrôle de version, peu importe ce que vous faites à tout moment dans le "temps" car le code est toujours quel que soit l'état dans lequel le fichier actuel est "enregistré" comme dans le système d'exploitation.
Si vous utilisez le contrôle de version, et que vous avez une charge de commentaires en tant que votre "liste de tâches", et que vous en corrigez et en supprimez le commentaire, puis répétez, puis répétez etc ... vous avez alors le code "work in progress" et les commentaires enregistrés dans votre historique de révision. Ce ne sera pas un problème si vous n'avez jamais besoin de revenir à un autre commit ou même à un "choix de cerise" plus tard (c'est par exemple là que vous prenez des commits spécifiques et les tirez dans une autre branche à utiliser). Mais sinon, cela pourrait être un problème.
On peut dire que cela peut être comparé aux "clichés" du logiciel de disque dur, comme Windows (la chose Restore). S'il prend un instantané contenant un virus, vous tuez le virus, mais vous devez ensuite revenir en arrière, vous pouvez revenir à un point où le virus est à nouveau présent.
Cette approche est également probable pour être un problème lorsque vous utilisez le contrôle de version et travailler avec d'autres développeurs, car alors ils doivent voir votre todo list qui ne leur est d'aucune utilité. En fait, c'est juste de l'encombrement qu'ils doivent ignorer et contourner. Dans nos équipes, nous supprimons toujours tous les commentaires, tels que l'ancien code ou les "notes". À moins qu'ils ne soient utiles - cependant, cela est très rare car nous avons une documentation pour "comment cela fonctionne", et un logiciel pour suivre ce qui doit être fait (alias todo).
De plus, lorsque vous travaillez sur un projet plus important, vous avez tendance à collaborer et à vous engager et à pousser souvent, il est donc possible que leur branche sur laquelle ils travaillent ait votre liste TODO s'ils ont fusionné votre branche avec la leur. Alors votre liste TODO est l'affaire de tous: D
En résumé, si vous ne travaillez pas seul et surtout lorsque vous utilisez le contrôle de version, il encombre l'historique et peut être encombré par d'autres développeurs.
Et, c'est une chose personnelle à certains égards, mais utiliser une base de code comme "liste de tâches" n'est pas vraiment idéal. Un jour, vous pourriez laisser quelque chose par accident, ou oublier de le commenter ou de le commenter par erreur.
Comme pour de nombreuses approches de l'architecture, du codage et de la façon dont vous-même ou votre équipe travaillez, chaque scénario peut exiger quelque chose de différent. Considérez donc les inconvénients mentionnés et les avantages de l'utilisation du contrôle de version et décidez si cela fonctionne pour vous.
Il semble que votre critique soit un peu dogmatique. Je ne suis pas sûr de jurer sur quelqu'un d'avoir commenté le code est PC ;-), ou même utile ;-)
Mais plus sérieusement, je pense que votre critique IS à droite, que vous devriez sérieusement envisager d'utiliser git (ou un autre système de contrôle de source, mais git est un choix judicieux).
Et cela peut alléger certains de vos besoins de commenter le code.
Mais avoir une liste TODO dans le code (qu'il s'agisse de listes à puces ou d'un ancien code) - est tout à fait raisonnable à mon avis. Mais vous voudrez peut-être reconsidérer un peu la façon dont vous le faites. Pour une chose - je suggère de penser à quelqu'un d'autre lisant votre code. Que quelqu'un d'autre puisse être vous, un an après avoir abandonné et rejoint un projet. Ou ce pourrait être quelqu'un d'autre entièrement. JUSTE rencontrer du code commenté est un peu déroutant. Peut-être quelque chose comme:
/*
* Need this sort of functionality added back before too long:
* .... OLD CODE HERE
*/
Personnellement, je penche davantage vers quelque chose comme ça:
* TODO:
* @todo Possible get rid of intermediate LRUCache_ object.
*
* @todo Find some reasonable/simple way to get
* LRUCache<PHRShortcutSpec, PHRShortcutSpec, PHRShortcutSpecNoAuthCacheTraits_> sRecentlyUsedCache (kMaxEltsInReceltlyUsedCache_);
* Working with ONE T argument
* Add(elt2cache).
...
et je me sens libre d'ajouter des "extraits de code" de l'ancien code comme utile.
Utiliser git est difficile (malheureusement). Il vous faudra un certain temps pour apprendre, et il peut sembler que cela ne fait pas partie de ce que vous essayez d'accomplir. Mais si vous voulez programmer de manière utile, vous devrez apprendre à le faire en tant que membre d'une équipe et à communiquer avec une équipe, et git est exactement la façon dont cela se fait de nos jours. Et une fois que vous aurez commencé à l'utiliser, vous trouverez que c'est un outil/béquille TRÈS utile, facilitant le développement de votre logiciel.
Bonne chance!
Il y a plusieurs raisons de commenter le code: -
- Ce n'est pas encore correct, et vous ne le commenterez pas quand il sera prêt.
- Vous le commentez temporairement pour modifier le comportement lors du débogage.
- Vous n'êtes pas sûr si le code est nécessaire, mais vous ne voulez pas le supprimer avant d'en avoir testé davantage.
- Le code est nécessaire pour certaines versions du logiciel, mais pas pour celle-ci.
- Le code est obsolète, mais il a fallu des siècles pour l'écrire et vous y êtes émotionnellement attaché. D'ailleurs, cela pourrait être utile un jour.
Le problème survient lorsque vous mettez le code au lit, puis y revenez quelques années plus tard pour effectuer une maintenance. Vous trouverez la base de code jonchée de code commenté. Il ne sera plus clair pourquoi tout cela est là, et c'est maintenant juste encombré.
Si vous utilisez un outil de contrôle de version à moitié décent, vous pouvez supprimer audacieusement tout code dont vous n'avez plus besoin, sachant que le système de contrôle de version le conserve encore. Un fichier différent entre les versions révélera ce qui a été supprimé. Une fois que vous avez implémenté le contrôle de version, le seul besoin de commenter est pour les choses temporaires. Si vous trouvez du code commenté dans des fichiers sur lesquels vous ne travaillez pas, vous pouvez simplement le supprimer.
Je ne vais pas répéter pourquoi vous devriez utiliser le contrôle de code source même pour des projets d'une seule personne, car il existe de nombreuses autres ressources qui vous diront de le faire. Mais un inconvénient majeur de votre approche actuelle est que si vous commentez le code, vous le cachez à votre IDE (si vous n'utilisez pas un IDE vous devriez probablement y penser).
Par exemple, si vous souhaitez renommer une méthode ou une classe, ou modifier le nombre de paramètres qu'une méthode prend, votre IDE devrait avoir une option de refactorisation pour ce faire qui trouvera toutes les références appropriées et mettez-les à jour en conséquence - mais il ne cherchera probablement pas dans les commentaires.
Au lieu d'essayer de deviner où vous devez apporter des modifications, faites-les simplement et laissez votre IDE vous dire où vos modifications ont provoqué la rupture. Vous pouvez ensuite commenter le code de manière plus chirurgicale, et j'espère pour une période plus courte avant de réparer ce qui s'est cassé.
C'est mauvais et vous devriez arrêter.
La raison se résume à essayer de faire une grande quantité de refactoring en une seule fois.
Si vous commentez de grandes sections de code, corrigez un peu et archivez, vous avez archivé du code non fonctionnel. et un tas de choses commentées que les autres supposeront anciennes et peuvent être ignorées
Si vous ne vous enregistrez pas souvent, vous accumulez des conflits de fusion et n'enregistrez pas les progrès pas à pas.
Vous devez changer votre pratique de travail afin que si vous devez vous arrêter à mi-chemin, tout fonctionne toujours.
Faites quelques pas et enregistrez-vous après chaque:
- extraire une interface
- écrire un test
- refactoriser une fonction
Ne marquez pas de gros morceaux de code comme étant les vôtres en les commentant et en les emportant pour travailler par vous-même jusqu'à ce qu'ils soient terminés ou que vous échouiez.
Si vous devez garder une trace de ce qui doit être fait, utilisez un tableau des tâches comme Scrum ou Trello