Nous sommes en train de refactoriser une base de code héritée de 20 ans et j'ai une discussion avec mon collègue sur le format des commentaires dans le code (plsql, java).
Il n'y a pas de format par défaut pour les commentaires, mais dans la plupart des cas, les gens font quelque chose comme ça dans le commentaire:
// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and commentle format proposé pour les commentaires futurs et passés que je veux est:
// {yyyy-mm-dd}, unique_author_company_id, commentMon collègue dit que nous n'avons besoin que du commentaire et que nous devons reformater tous les commentaires passés et futurs dans ce format:
// commentMes arguments:
- Je dis pour des raisons de maintenance, il est important de savoir quand et qui a fait un changement (même cette information est dans le SCM).
- Le code est vivant et pour cette raison a une histoire.
- Parce que sans les dates de modification, il est impossible de savoir quand une modification a été introduite sans ouvrir l'outil SCM et rechercher dans l'historique des objets longs.
- parce que l'auteur est très important, un changement d'auteurs est plus crédible qu'un changement d'authory
- Raisons d'agilité, pas besoin d'ouvrir et de naviguer dans l'outil SCM
- les gens auraient plus peur de changer quelque chose que quelqu'un a fait il y a 15 ans, que quelque chose qui a été récemment créé ou changé.
- etc.
Arguments de mon collègue:
- L'histoire est dans le SCM
- Les développeurs ne doivent pas connaître l'historique du code directement dans le code
- Les packages contiennent 15 000 lignes et les commentaires non structurés rendent ces packages plus difficiles à comprendre
Quelle est selon vous la meilleure approche? Ou avez-vous une meilleure approche pour résoudre ce problème?
java
c#
programming-practices
code-quality
comments
Diego Alvarez
la source
la source
Réponses:
Observations générales
Je crois beaucoup que les commentaires sont pour pourquoi (pas comment) . Lorsque vous commencez à ajouter des commentaires sur la façon dont vous tombez dans le problème, rien n'impose que les commentaires soient conservés par rapport au code (le pourquoi ne changera généralement pas (l'explication du pourquoi peut être améliorée au fil du temps)).
De la même manière, date / authorInfo ne vous rapporte rien quant à la raison pour laquelle le code a été fait de cette façon; tout comme la façon dont il peut dégénérer au fil du temps, car aucun outil n'est appliqué. De plus, les mêmes informations sont déjà stockées dans le système de contrôle de source (vous dupliquez donc l'effort (mais de manière moins fiable)).
En passant par les arguments:
Pourquoi. Aucune de ces choses ne me semble importante pour maintenir le code. Si vous avez besoin de parler à l'auteur, il est relativement simple de trouver ces informations à partir du contrôle de source.
L'historique est stocké dans le contrôle de source.
Croyez-vous également que le commentaire a été rédigé par cette personne.
Howles commentaires ont tendance à se dégrader avec le temps, ce genre d'histoire devient donc peu fiable. Les systèmes de contrôle des sources, d'autre part, conserveront un historique très précis et vous pourrez voir avec précision quand des commentaires ont été ajoutés / supprimés.Si vous faites confiance aux données dans un commentaire.
Un des problèmes avec ce genre de choses est que les commentaires deviennent incorrects par rapport au code. Retour à l'outil approprié pour le travail. Le système de contrôle des sources le fera correctement sans intervention de l'utilisateur. Si votre système de contrôle de source est un problème, vous devrez peut-être apprendre à l'utiliser de manière plus appropriée (car cette fonctionnalité est généralement facile) ou s'il ne le prend pas en charge, trouver un meilleur système de contrôle de source.
Tous les auteurs (à part vous) sont également crédibles.
Si votre outil de contrôle des sources est si lourd que vous vous en servez de manière incorrecte ou (il est plus probable) que vous utilisez le mauvais ensemble d'outils pour accéder au système de contrôle des sources.
Si le code a duré 15 ans, il est plus susceptible d'être plus solide que le code qui n'a duré que 6 mois sans avoir besoin d'être révisé. Le code stable a tendance à rester stable, le code bogué a tendance à devenir plus complexe au fil du temps (car la raison pour laquelle il est bogué est que le problème n'est pas aussi simple qu'à première vue).
Encore plus de raisons d'utiliser le contrôle de code source pour obtenir des informations.
Oui. La meilleure raison pour le moment.
Si j'ai vraiment besoin de ces informations, je les rechercherai dans le contrôle de code source.
Sinon, ce n'est pas pertinent.
Les commentaires doivent être une description de la raison pour laquelle vous faites quelque chose de toute façon.
Les commentaires ne doivent PAS décrire le fonctionnement du code (sauf si l'algorithme n'est pas évident).
la source
J'appuie fortement votre collègue. Vous ne vous en sortirez pas sans regarder le SCM de toute façon si vous voulez comprendre pourquoi quelque chose a été changé, sauf si vous gardez l'ancien code dans un commentaire.
Si le code est trop complexe pour être compris sans écrire des tonnes de commentaires, je vous suggère d'investir de l'énergie dans la refactorisation pour rendre le code lisible / maintenable sans tonnes de commentaires.
Après tout, vous embauchez des programmeurs, pas des conteurs ;-)
la source