Quelle est la meilleure approche pour les commentaires de code en ligne?

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 comment

le format proposé pour les commentaires futurs et passés que je veux est:

// {yyyy-mm-dd}, unique_author_company_id, comment

Mon 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:

// comment

Mes 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?

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:

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).

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.

Le code a la vie pour cette raison avait une histoire.

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.

Parce que sans la date 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.

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.

parce que l'auteur est très important, un changement d'authorx est plus crédible qu'un changement d'authory

Tous les auteurs (à part vous) sont également crédibles.

Raisons d'agilité, pas besoin d'ouvrir et de naviguer dans l'outil SCM

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.

les gens auraient peur de changer quelque chose que quelqu'un a fait il y a 15 ans, plutôt que quelque chose qui a été fait récemment ...

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.

L'histoire est dans le SCM

Oui. La meilleure raison pour le moment.

Les développeurs ne doivent pas connaître l'historique du code directement dans le code

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 paquets obtiennent 15k lignes de long et des commentaires non structurés que ces paquets sont plus difficiles à comprendre

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).

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 ;-)