Est-ce une mauvaise pratique de ne pas supprimer les fichiers redondants immédiatement de VCS, mais plutôt de les marquer comme «À supprimer» avec des commentaires en premier?

53

Je voulais savoir si ma façon de traiter les fichiers source à supprimer du contrôle de version pouvait être considérée comme une mauvaise pratique.

Je veux vous expliquer en vous basant sur cet exemple:

Je me suis récemment mis très en colère parce que je devais trier minutieusement les classes Java dans un programme qui était essentiellement du code mort, mais il n'était nulle part documenté et non commenté dans ces classes Java. Bien sûr, ils devaient être supprimés, mais avant que je supprime ce genre de choses redondantes, j'ai une habitude - certains diront peut-être étrange -:

Je ne supprime pas immédiatement ces fichiers redondants via SVN-> Supprimer (commande de choix du système de contrôle de version de votre système de contrôle de version), mais placez plutôt des commentaires dans ces fichiers (je renvoie à la fois au début et à la fin) auxquels ils vont accéder. être supprimé + mon nom + la date et aussi - plus important encore - pourquoi ils sont supprimés (dans mon cas, car ils étaient morts, code source de confusion). Ensuite, je les enregistre et les engage dans le contrôle de version. La prochaine fois que je devrai valider / archiver quelque chose dans le projet pour le contrôle de version, j'appuierai sur SVN-> Supprimer, puis ils seront finalement supprimés dans Version Control - toujours bien sûr restaurable grâce à des révisions et c'est pourquoi j'ai adopté cette habitude.

Pourquoi faire cela au lieu de les supprimer tout de suite?

Ma raison est, je veux avoir des marqueurs explicites au moins dans la dernière révision dans laquelle ces fichiers redondants existaient, pourquoi ils méritaient d'être supprimés. Si je les supprime tout de suite, ils sont supprimés, mais rien n’indique pourquoi ils ont été supprimés. Je veux éviter un scénario typique comme celui-ci:

"Hmm ... pourquoi ces fichiers ont-ils été supprimés? Je fonctionnais bien avant." (Presses 'revert' -> Le type qui a annulé sa visite est parti pour toujours ou n'est plus disponible dans les prochaines semaines et le prochain cessionnaire doit découvrir fastidieusement ce que sont ces fichiers.)

Mais ne notez-vous pas pourquoi ces fichiers ont été supprimés dans les messages de validation?

Bien sûr, mais un message de validation n’est parfois pas lu par des collègues. Lorsque vous essayez de comprendre le code (dans mon cas, mort), vous ne vérifiez pas d'abord le journal de contrôle de version avec tous les messages de validation associés. Au lieu de parcourir le journal, un collègue peut voir tout de suite que ce fichier est inutile. Cela lui fait gagner du temps et il / elle sait que ce fichier a probablement été restauré pour de mauvais (ou au moins cela soulève une question.

Bruder Lustig
la source
120
Vous essayez essentiellement de reproduire le travail de votre système de contrôle de version directement dans le fichier. Faire une telle chose soulèverait certainement un drapeau dans ma tête. Si vos collègues ne lisent pas les messages de validation et ressuscitent un fichier qui a été supprimé à juste titre et passe le code en revue, il y a certainement quelque chose qui ne va pas dans votre équipe et c'est une excellente occasion de mieux leur apprendre.
Vincent Savard
6
@ GregBurghardt Cela semble être une bonne question à propos d'une mauvaise idée. Peut-être les gens votent-ils en se basant sur la deuxième partie de celle-ci (quand, l’OMI, ils devraient voter pour la première)?
Ben Aaronson
13
"La prochaine fois que je dois valider / archiver quelque chose dans le projet pour le contrôle de version, j'appuie sur SVN-> Supprimer" Voulez-vous dire que vous les supprimez dans un commit (potentiellement) totalement indépendant?
Kevin
21
Bien sûr, mais un message de validation n’est parfois pas lu par des collègues. - S'ils ne vérifient pas le message de validation, il est prudent de supposer qu'ils ne sont pas intéressés par la raison pour laquelle le fichier a été supprimé ... sinon, ils devraient vérifier le message de validation.
Ant P
9
Si je veux savoir pourquoi un fichier a disparu de mon départ VCS, je vais regarder dans l'historique des modifications d' abord , et si cela n'explique pas les choses, je vais lire la discussion qui a eu lieu lors de la révision de la suppression. (Si vous ne disposez pas d'un processus de révision de code que chaque modification subit, vous rencontrez de plus gros problèmes.) Et si cela n'a toujours pas été clair, je parlerai à quiconque a supprimé le fichier. Je pourrais regarder le contenu précédent du fichier pour essayer de découvrir ce qu’il faisait auparavant, mais pas pour une explication de la suppression.
dimanche

Réponses:

110

Le problème lié à l'ajout d'un commentaire à un fichier à supprimer, au lieu de le supprimer dans le contrôle de code source et d'y ajouter l'explication, est que si les développeurs ne lisent pas les messages de validation, ils liront sûrement les commentaires dans le code source.

D'un point de vue externe, cette méthodologie semble s'enraciner dans une vision très conservatrice du contrôle à la source.

"Et si je supprime ce fichier inutilisé alors que quelqu'un en a besoin?" quelqu'un pourrait demander.

Vous utilisez le contrôle de source. Annulez la modification ou, encore mieux, parlez à la personne qui a supprimé le fichier (communiquez).

"Et si je supprime le fichier mort, alors quelqu'un recommence à l'utiliser et apporte des modifications?" quelqu'un d'autre pourrait demander.

Encore une fois, vous utilisez le contrôle de source. Vous obtiendrez un conflit de fusion qu'une personne doit résoudre. La réponse ici, comme pour la dernière question, est de communiquer avec vos coéquipiers.

Si vous pensez vraiment qu'un fichier doit être supprimé, communiquez avant de le supprimer du contrôle de source. Peut-être que cela a récemment cessé d'être utilisé, mais une fonctionnalité à venir pourrait en avoir besoin. Vous ne le savez pas, mais l'un des autres développeurs pourrait le faire.

S'il doit être supprimé, supprimez-le. Coupez le gras de la base de code.

Si vous avez créé un "oopsie" et que vous avez réellement besoin du fichier, souvenez-vous que vous utilisez le contrôle de source pour pouvoir le récupérer.

Vincent Savard, dans un commentaire sur la question, a déclaré:

... Si vos collègues ne lisent pas les messages de validation et ressuscitent un fichier qui a été supprimé à juste titre et passe le code en revue, il y a définitivement quelque chose qui ne va pas dans votre équipe et c'est une excellente occasion de mieux leur apprendre.

C'est un conseil judicieux. Les revues de code devraient attraper ce genre de chose. Les développeurs doivent consulter les messages de validation lorsqu'une modification inattendue est apportée à un fichier, ou qu'un fichier est supprimé ou renommé.

Si les messages de validation ne racontent pas l'histoire, les développeurs doivent également rédiger de meilleurs messages de validation.

Avoir peur de supprimer du code ou des fichiers indique un problème systémique plus profond lié au processus:

  • Manque de critiques de code précises
  • Manque de compréhension sur le fonctionnement du contrôle de source
  • Manque de communication d'équipe
  • Messages de validation médiocres de la part des développeurs

Ce sont les problèmes à résoudre, vous éviterez ainsi de jeter des pierres dans une maison de verre lorsque vous supprimez du code ou des fichiers.

Greg Burghardt
la source
3
"supposer que si les développeurs ne lisent pas les messages de validation, ils liront sûrement les commentaires dans le code source." Je pense que c'est une assez bonne hypothèse. Un développeur qui modifie un fichier doit effectivement consulter le fichier pour accomplir la tâche, mais rien ne l'oblige à consulter l'historique du contrôle de source.
AShelly
7
@AShelly: une tâche de développeur consiste rarement à modifier un commentaire. Les tâches impliquent de changer le code, ce sur quoi le développeur se concentre - et non les commentaires.
Greg Burghardt
21
@AShelly Ce n'est pas parce qu'ils doivent ouvrir un fichier qu'ils liront un commentaire particulier en haut. Le public cible de ce changement est le type de développeur le plus inconscient, celui qui pense que ses besoins sont ses seuls besoins et que tout devrait tourner autour de lui. Ceux-ci sont peu susceptibles de lire votre commentaire poli. Pire encore, ils sont susceptibles de le lire, puis de revenir simplement à la version la plus ancienne.
Cort Ammon
5
@AShelly - à titre d'exemple, j'ouvre couramment des fichiers vers un emplacement. En VS, je peux ouvrir directement une méthode en utilisant les menus déroulants situés en haut ou le menu contextuel "Aller à la définition". Je ne verrais jamais le haut du fichier. Également dans Sublime Text, j'ouvre fréquemment à une ligne. Leur dialogue ouvert users.rb: 123 ouvre user.rb directement à la ligne 123. De nombreux éditeurs de code proposent des options très similaires.
coteyr
2
En plus de ce qui précède, plus les tâches de nettoyage de ce type sont complexes, moins les gens sont susceptibles de les effectuer régulièrement. Si vous pouvez vous en tirer en toute simplicité, cela réduit «l’énergie d’activation» pour vous et pour tous les autres. Ceci est particulièrement important si vous essayez d'encourager un changement de pratique pour les autres membres de l'équipe. Plus la procédure est complexe, plus il est difficile d’obtenir l’adhésion.
xdhmoore
105

Oui c'est une mauvaise pratique.

Vous devriez mettre l'explication de la suppression dans le message de validation lorsque vous validez la suppression des fichiers.

Les commentaires dans les fichiers source doivent expliquer le code tel qu'il se présente actuellement . Les messages de validation doivent expliquer pourquoi les modifications ont été apportées à la validation. L'historique des validations du fichier explique donc son historique.

Ecrire des commentaires expliquant les changements directement dans la source elle-même rendra le code beaucoup plus difficile à suivre. Pensez-y: si vous commentez dans le fichier chaque fois que vous modifiez ou supprimez du code, les fichiers seront bientôt submergés de commentaires sur l'historique des modifications.

JacquesB
la source
6
Peut-être ajouter la réponse à la question: est-ce une mauvaise pratique? Oui, parce que ...
Juan Carlos Coto Le
1
Je fais parfois la même chose (que OP) car il est plus facile de dégager le commentaire que de revenir en arrière. Dans de rares cas, même si le code est compilé et passe avec succès les tests automatiques, il existe une raison pour l'existence de ce code que j'ai oublié de savoir si le testeur manuel le détecte. Dans ce scénario rare, au lieu de souffrir énormément ou de revenir sur plusieurs choses plus tard, je ne fais que commenter le code (et comment il peut être amélioré)
Andrew Savinykh
2
@ AndrewSavinykh C'est différent, vous commentez du code que vous n'êtes toujours pas sûr de vouloir supprimer.
Arrêtez de faire du mal à Monica le
6
@AndrewSavinykh «douleur majeure ou revirement de choses plusieurs fois par la suite» - je me demande quel contrôle de version vous utilisez; cela ne devrait pas être une douleur majeure. Ce n'est certainement pas dans Git, du moins pas après l'avoir fait plusieurs fois et appris ce qu'il faut surveiller ... et à condition que votre histoire ne soit pas encombrée de commits inutiles de va-et-vient qui vous donnent conflits tous les autres fusionnent. Et les commits qui se contentent de commenter quelque chose sont plutôt enclins à le faire ...
partir du
4
@AndrewSavinykh oui, et ce n'est pas comme si je n'avais pas rencontré ces problèmes - des projets dont les responsables n'ont jamais vraiment travaillé avec le contrôle de version et ont mis beaucoup d'informations dans des commentaires qui auraient dû être réellement des messages de validation, mais plutôt ajouté un nouveau manuel - annulant-valide à la place L’état du référentiel qui en a résulté a rendu le conflit beaucoup plus amusant dans toutes les grandes bases… Mais, et c’est ce que je veux dire, ces problèmes sont souvent causés en grande partie par des solutions de contournement comme celle que vous défendez ici.
gauche du
15

À mon avis les deux de vos options sont pas les meilleures pratiques , par opposition à une mauvaise pratique:

  1. L'ajout de commentaires n'ajoute une valeur que s'il est lu par ceux-ci.
  2. La suppression du VCS (avec une raison dans la description du changement) peut avoir un impact sur un produit livrable essentiel et de nombreuses personnes ne lisent pas la description du changement, en particulier sous pression.

Ma pratique préférée - principalement en raison d'avoir été mordu plusieurs fois au fil des ans, en gardant à l'esprit que vous ne savez pas toujours où et par qui votre code est utilisé - consiste à:

  1. Ajoutez un commentaire indiquant qu’il s’agit d’un candidat à la suppression et à une dépréciation #warning ou similaire (la plupart des langues ont une sorte de mécanisme, par exemple en Java , dans le pire des cas, une printdéclaration ou similaire suffira), idéalement avec une sorte de délai et avec les coordonnées. Cela alertera tous ceux qui utilisent encore le code. Ces avertissements sont normalement présents dans chaque fonction ou classe si de telles choses existent .
  2. Après un certain temps, mettez l'avertissement à niveau avec une étendue de fichier standard #warning(certaines personnes ignorent les avertissements de dépréciation et certaines chaînes d'outils ne les affichent pas par défaut).
  3. Remplacez ultérieurement l'étendue du fichier #warningpar un #erroréquivalent ou un équivalent. Le code sera cassé au moment de la construction, mais peut être supprimé si cela est absolument nécessaire, mais la personne qui l'a supprimé ne peut pas l'ignorer. (Certains développeurs ne lisent ni ne traitent les avertissements ou en ont tellement qu'ils ne peuvent pas séparer les plus importants).
  4. Enfin, marquez le (s) fichier (s) (après ou à la date d'échéance) comme supprimé dans le VCS.
  5. Si la suppression d' un paquet entier / bibliothèque / etc au stade de la mise en garde que je voudrais ajouter un README.txt ou README.html ou similaire avec les informations quand et pourquoi il est prévu de se débarrasser du paquet et il suffit de laisser ce fichier, avec changer pour dire quand il a été supprimé, en tant que seul contenu du package pendant un certain temps après avoir supprimé le reste du contenu.

L'un des avantages de cette approche est que certains systèmes de gestion de versions (CVS, PVCS, etc.) ne suppriment pas un fichier existant à la caisse s'il a été supprimé dans le VCS. Il donne également aux développeurs consciencieux, ceux qui règlent tous leurs avertissements, beaucoup de temps pour résoudre le problème ou faire appel de la suppression. Cela oblige également les développeurs restants à au moins regarder l'avis de suppression et à se plaindre .

Notez que #warning/ #errorest un mécanisme C / C ++ qui provoque un avertissement / une erreur suivi du texte fourni lorsque le compilateur rencontre ce code, java / java-doc possède une @Deprecatedannotation pour émettre un avertissement sur l'utilisation et @deprecatedfournir certaines informations, etc. Recettes à faire de même en python et j'ai vu l' asserthabitude de fournir des informations similaires à #errordans le monde réel.

Steve Barnes
la source
7
En particulier, puisque cette question mentionne Java, utilisez le @deprecatedcommentaire JavaDoc et l' @Deprecatedannotation .
200_success
8
Cela semble plus approprié lorsque vous souhaitez vous débarrasser de quelque chose qui est encore utilisé. L'avertissement peut rester jusqu'à ce que tous les usages soient terminés, mais une fois que le code est mort, il doit être immédiatement supprimé.
Andy
6
@Andy L'un des problèmes avec le code de type de bibliothèque, en particulier dans les sources ouvertes ou les grandes organisations, est que vous pouvez penser que le code est mort, mais que son utilisation est active dans un ou plusieurs endroits que vous n'auriez jamais imaginés. Il est parfois nécessaire de supprimer le code, car il est vraiment mauvais ou comporte des risques pour la sécurité, mais vous ne savez pas si et où il est utilisé.
Steve Barnes
1
@ 200_success merci - mon expérience en C / C ++ - a été ajoutée à la réponse.
Steve Barnes
1
@SteveBarnes Peut-être mais ce n'est pas ce que le PO demande. Il a vérifié que le code est mort.
Andy
3

Oui, je dirais que c'est une mauvaise pratique, mais pas parce que cela se trouve dans les fichiers plutôt que dans le message de validation. Le problème est que vous essayez de faire un changement sans communiquer avec votre équipe.

Chaque fois que vous apportez des modifications au tronc (ajout, suppression ou modification de fichiers, de quelque manière que ce soit), vous devez, avant de vous réengager sur le tronc, en parler directement à un membre (ou aux membres) de l'équipe qui serait directement bien informés à leur sujet (essentiellement, discutez de ce que vous mettriez dans ces en-têtes directement avec vos coéquipiers). Cela garantira que (1) le code que vous supprimez doit vraiment être supprimé et que (2) votre équipe sera beaucoup plus susceptible de savoir que le code est supprimé et ne tentera donc pas de revenir sur vos suppressions. Sans parler du fait que vous obtiendrez également une détection de bogues et autres pour le code que vous ajoutez.

Bien sûr, lorsque vous modifiez des éléments importants, vous devez également les inclure dans le message de validation, mais comme vous en avez déjà parlé, il n'est pas nécessaire que ce soit la source des annonces importantes. La réponse de Steve Barnes aborde également de bonnes stratégies à utiliser si le groupe d'utilisateurs potentiels pour votre code est trop important (par exemple, en utilisant les marqueurs obsolètes de votre langue au lieu de supprimer les fichiers au préalable).

Si vous ne voulez pas rester aussi longtemps sans vous engager (c’est-à-dire que votre modification a plus de sens comme plusieurs révisions), il est judicieux de créer une branche à partir d’une ligne de commande et de la valider dans la branche, puis de fusionner la branche avec celle-ci lorsque la le changement est prêt. De cette façon, le VCS continue de sauvegarder le fichier pour vous, mais vos modifications n’affectent en aucune façon la jonction.

TheHinsinator
la source
1

Un problème connexe lié à des projets reposant sur plusieurs plates-formes et configurations. Ce n’est pas parce que j’ai déterminé qu’il est mort que c’est une détermination correcte. Notez que l'utilisation en cours peut toujours signifier une dépendance résiduelle qui doit encore être éliminée, et certaines peuvent avoir été manquées.

Donc (dans un projet C ++) j'ai ajouté

#error this is not as dead as I thought it was

Et vérifié cela. Attendez que la reconstruction de toutes les plates-formes normales soit terminée et que personne ne s'en plaint. Si quelqu'un le trouvait, il serait facile de supprimer une ligne plutôt que d'être dérouté par un fichier manquant.

Je conviens en principe que les commentaires que vous avez mentionnés font double emploi avec la fonctionnalité qui devrait être intégrée au système de gestion des versions . Mais, vous pouvez avoir des raisons spécifiques pour le supplimenter. Ne pas connaître l'outil VCS n'en fait pas partie.

JDługosz
la source
-1

Sur le continuum des mauvaises pratiques, c'est assez mineur. Je le ferai de temps en temps, quand je veux vérifier une branche et pouvoir voir l'ancien code. Cela peut faciliter la comparaison avec le code de remplacement. Je reçois habituellement un commentaire de révision de code "cruft". Avec un peu d'explication, je passe l'examen du code.

Mais ce code ne devrait pas durer longtemps. Je supprime généralement au début du prochain sprint.

Si certains de vos collègues ne lisent pas les messages de validation ou ne vous demandent pas pourquoi vous avez laissé le code dans le projet, le problème ne réside pas dans un mauvais style de codage. Vous avez un problème différent.

Tony Ennis
la source
cela ne semble rien offrir de substantiel sur les points soulevés et expliqués dans les 6 réponses précédentes
gnat
-3

vous pouvez également refactoriser la classe et la renommer avec un préfixe UNUSED_Classname avant de tirer votre cascade. Ensuite, vous devez aussi commettre directement l'opération de suppression

  • Étape 1: renommez la classe, ajoutez votre commentaire, validez
  • Étape 2: supprimer le fichier et commettre

Si c'est du code mort, supprimez-le. N'importe qui en a besoin, il peut revenir en arrière, mais l'étape de changement de nom l'empêchera de l'utiliser directement sans y penser.

Apprenez également aux utilisateurs comment consulter tous les messages de validation d'un fichier. Certaines personnes ne savent même pas que c'est possible.

utilisateur275398
la source
6
"Refactoring" ne signifie pas vraiment ce que vous pensez
Nik Kyriakides Le
6
Il n'est pas nécessaire de renommer la classe / méthode pour s'assurer qu'elle est inutilisée, sa suppression fonctionne aussi bien. Au lieu de cela, la procédure est la même que pour tout autre changement: 1) supprimer le code mort , 2) exécuter les tests , 3) s’ils réussissent, commettez-les avec commentaire .
Schwern
1
@ user275398 Je pense aussi que renommer les fichiers, c'est vraiment trop. Et aussi du point de vue technologique, SVN traite le changement de nom comme le fichier est supprimé et créé avec un nouveau nom. Vous avez alors une rupture dans l'historique. Si vous souhaitez restaurer le fichier renommé et consulter son journal SVN, l'historique antérieur au changement de nom n'est pas disponible. Pour cela, vous devez rétablir le fichier avec l'ancien nom. Le refactoring est une autre chose, le refactoring consiste à organiser le code existant dans une nouvelle structure.
Bruder Lustig
@BruderLustig: Un bon logiciel ne fera certainement pas cela. Git a git mv, qui retrace l'histoire. Mercurial a également hg mv. On dirait que cela svn movedevrait aussi fonctionner pour SVN?
wchargin
@wchargin Non, il git mvne fait que déplacer le fichier et procéder à la suppression et à la création du fichier. Tout le suivi de mouvement se produit lorsque vous exécutez git log --followet similaire. gitn'a aucun moyen de suivre les renommés, il ne suit en réalité pas les modifications ; au lieu de cela, il suit les états au moment de la validation et découvre ce qui a changé au moment où vous inspectez l'historique.
Maaartinus