Est-ce une mauvaise pratique de ne pas supprimer immédiatement les fichiers redondants de VCS, mais plutôt de les marquer comme "À supprimer" avec des commentaires en premier?
Je voulais savoir si la façon dont je traite les fichiers source qui doivent être supprimés du contrôle de version peut être considérée comme une mauvaise pratique.
Je veux vous l'expliquer sur la base de cet exemple:
J'ai récemment été très en colère parce que je devais trier fastidieusement 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 de supprimer ces éléments redondants, j'ai une - certains diront peut-être étrange - habitude:
Je ne supprime pas ces fichiers redondants immédiatement via SVN-> Supprimer (remplacez-les par la commande delete de votre système de contrôle de version de votre choix), mais placez plutôt des commentaires dans ces fichiers (je me réfère à la fois en tête et en pied de page) qu'ils vont être supprimé + mon nom + la date et aussi - plus important encore - POURQUOI ILS SONT SUPPRIMÉS (dans mon cas, parce qu'ils étaient morts, code déroutant). Ensuite, je les enregistre et les soumets au contrôle de version. La prochaine fois que je dois valider/archiver quelque chose dans le projet pour le contrôle de version, j'appuie sur SVN-> Supprimer, puis ils sont finalement supprimés dans le contrôle de version - toujours bien sûr restituable par le biais de 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 que 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 la raison pour laquelle ils ont été supprimés n'est documentée nulle part. Je veux éviter un scénario typique comme celui-ci:
"Hmm ... pourquoi ces fichiers ont-ils été supprimés? J'ai bien fonctionné avant." (Presses 'revert' -> le gars qui est revenu alors est parti pour toujours ou n'est pas disponible dans les prochaines semaines et le prochain cessionnaire doit découvrir comme moi fastidieusement de quoi ces fichiers sont faits)
Mais ne voyez-vous pas pourquoi ces fichiers ont été supprimés dans les messages de validation?
Bien sûr que oui, mais un message de validation n'est parfois pas lu par mes collègues. Ce n'est pas une situation typique que lorsque vous essayez de comprendre le code (dans mon cas, mort), vous vérifiez 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 elle sait que ce fichier a probablement été restauré pour de mauvais (ou du moins cela soulève une question.
Le problème avec l'ajout d'un commentaire à un fichier qu'il doit être supprimé, au lieu de le supprimer dans le contrôle de code source et d'y mettre l'explication, est l'hypothèse que si les développeurs ne lisent pas les messages de validation, ils liront sûrement les commentaires dans le code source.
Du point de vue d'un étranger, cette méthodologie semble être ancrée dans une vision très conservatrice du contrôle des sources.
"Et si je supprime ce fichier inutilisé et que quelqu'un en a besoin?" quelqu'un pourrait demander.
Vous utilisez le contrôle de code source. Annulez la modification, ou mieux encore parlez à la personne qui a supprimé le fichier (communiquez).
"Et si je supprime le fichier mort, puis quelqu'un recommence à l'utiliser et ils font des changements?" quelqu'un d'autre pourrait demander.
Encore une fois, vous utilisez le contrôle de code 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 doutez vraiment qu'un fichier doit être supprimé, communiquez avant en le supprimant du contrôle de code source. Peut-être qu'il a récemment cessé d'être utilisé, mais une fonctionnalité à venir pourrait l'exiger. Vous ne le savez pas, mais l'un des autres développeurs le pourrait.
S'il doit être retiré, retirez-le. Coupez le gras de la base de code.
Si vous avez fait une "oopsie" et que vous avez réellement besoin du fichier, n'oubliez pas que vous utilisez le contrôle de code source pour pouvoir récupérer le fichier.
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 qui passe le contrôle du code, il y a certainement quelque chose qui ne va pas dans votre équipe, et c'est une excellente occasion de mieux leur apprendre.
C'est un bon conseil. 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 écrire de meilleurs messages de validation.
Avoir peur de supprimer du code ou de supprimer des fichiers indique un problème systémique plus profond avec le processus:
- Manque d'examens de code précis
- Manque de compréhension du fonctionnement du contrôle de code source
- Manque de communication d'équipe
- Mauvais messages de validation de la part des développeurs
Ce sont les problèmes à résoudre, vous n'avez donc pas l'impression de jeter des pierres dans une serre lorsque vous supprimez du code ou des fichiers.
Oui, c'est une mauvaise pratique.
Vous devez 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 apparaît actuellement . Les messages de validation doivent expliquer pourquoi les changements dans la validation ont été effectués, donc l'historique de validation du fichier explique son historique.
Écrire des commentaires expliquant les changements directement dans la source elle-même rendra le code beaucoup plus difficile à suivre. Pensez-y: si vous commentez 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.
À mon avis les deux de vos options ne sont pas les meilleures pratiques , par opposition à mauvais, pratiquez:
- L'ajout de commentaires n'ajoute de valeur que si quelqu'un lit ces commentaires.
- La simple suppression du VCS (avec une raison dans la description du changement) peut avoir un impact sur un livrable critique et de nombreuses personnes ne lisent pas la description du changement, en particulier sous pression.
Ma pratique préférée - en grande partie parce qu'elle a été mordue plusieurs fois au fil des ans, en gardant à l'esprit que vous ne savez pas toujours où ni par qui votre code est utilisé - consiste à:
- Ajoutez un commentaire indiquant qu'il est candidat à la suppression et un dépréciation
#warningou similaire, (la plupart des langues ont une sorte de mécanisme, par exemple dans Java , dans le pire des cas une instructionprintou similaire suffira), idéalement avec une sorte d'échéance et des coordonnées. Cela alertera toute personne qui utilise encore le code . Ces avertissements sont normalement à l'intérieur de chaque fonction ou classe si de telles choses existent. - Après un certain temps, mettez à niveau l'avertissement vers une étendue de fichier standard
#warning(certaines personnes ignorent les avertissements de dépréciation et certaines chaînes d'outils n'affichent pas ces avertissements par défaut). - Remplacez ultérieurement la portée du fichier
#warningavec un#errorou équivalent - cela cassera le code au moment de la construction mais peut, si c'est absolument nécessaire, être supprimé mais la personne qui le supprime ne peut pas l'ignorer. (Certains développeurs ne lisent ou n'adressent aucun avertissement ou en ont tellement qu'ils ne peuvent pas séparer les plus importants). - Enfin, marquez le ou les fichiers (à la date d'échéance ou après) comme supprimés dans le VCS.
- Si vous supprimez un package/bibliothèque/etc entier au stade d'avertissement, j'ajouterais un fichier README.txt ou README.html ou similaire avec des informations sur quand et pourquoi il est prévu de se débarrasser du package = et laisser juste ce fichier, avec un changement pour dire quand il a été supprimé, comme seul contenu du paquet pendant un certain temps après avoir supprimé le reste du contenu.
Un avantage de cette approche est que certains systèmes de versioning (CVS, PVCS, etc.) ne supprimera pas un fichier existant fichier à la caisse s'il a été supprimé dans le VCS. Cela donne également aux développeurs consciencieux, ceux qui corrigent 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 consulter l'avis de suppression et à se plaindre beaucoup.
Notez que #warning/#error est un mécanisme C/C++ qui provoque un avertissement/erreur suivi du texte fourni lorsque le compilateur rencontre ce code, Java/java-doc a @Deprecated annotation pour émettre un avertissement sur l'utilisation & @deprecated pour fournir des informations, etc. il y a recettes pour faire de même dans python et j'ai vu assert utilisé pour fournir des informations similaires à #error dans le monde réel.
Oui, je dirais que c'est une mauvaise pratique, mais pas parce que c'est 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 devriez, avant de vous réengager dans le tronc, parler de ces changements directement avec un membre (ou membres de l'équipe qui seraient directement 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 donc de ne pas essayer d'annuler vos suppressions. Sans oublier que vous obtiendrez également la détection de bogues et autres pour le code que vous ajoutez.
Bien sûr, lorsque vous changez de gros trucs, vous devez également le mettre dans le message de validation, mais parce que vous en avez déjà discuté, il n'a pas besoin d'être la source d'annonces importantes. réponse de Steve Barnes traite également de bonnes stratégies à utiliser si le pool potentiel d'utilisateurs de votre code est trop important (par exemple, en utilisant les marqueurs obsolètes de votre langue au lieu de supprimer les fichiers au début).
Si vous ne voulez pas aller aussi longtemps sans vous engager (c.-à-d. Que votre modification est plus logique que plusieurs révisions), c'est une bonne idée de créer une branche à partir du tronc et de vous engager dans la branche, puis de fusionner la branche dans le tronc lorsque le le changement est prêt. De cette façon, le VCS sauvegarde toujours le fichier pour vous, mais vos modifications n'affectent en aucune façon le tronc.
Un problème lié aux projets qui s'appuient sur plusieurs plates-formes et configurations. Ce n'est pas parce que [~ # ~] i [~ # ~] qu'il est mort qu'il ne s'agit pas d'une détermination correcte. Notez que mort en cours d'utilisation peut encore signifier une dépendance résiduelle qui doit encore être éliminée, et certains peuvent avoir été manqués.
Donc (dans un projet C++) j'ai ajouté
#error this is not as dead as I thought it was
Et je l'ai vérifié. Attendez qu'il passe à travers la reconstruction de toutes les plates-formes normales et que personne ne s'en plaint. Si quelqu'un le trouvait, il serait facile de supprimer une ligne au lieu d'être dérouté par un fichier manquant.
Je suis d'accord en principe que les commentaires que vous mentionnez reproduisent la fonctionnalité qui devrait être effectuée dans le système de gestion des versions . Mais, vous pouvez avoir raisons spécifiques pour compléter cela. Ne pas connaître l'outil VCS n'en fait pas partie.