Gestion de la configuration - Historique dans les commentaires de code

Question

Permettez-moi de poser quelques informations générales avant de poser ma question:

J'ai récemment rejoint un nouveau groupe de développement logiciel utilisant les outils Rational de gestion de la configuration, notamment un système de contrôle de la source et de gestion des modifications. En plus de ces outils, l'équipe a pour pratique standard de noter tout changement de code sous forme de commentaire dans le code, tel que:

///<history>
   [mt] 3/15/2009  Made abc changes to fix xyz
///</history>

L’objet officiel de la norme de commentaire est que "les commentaires permettent une traçabilité de l’exigence à la modification du code".

Je me prépare à présenter un argument selon lequel cette pratique est inutile et redondante; que l'équipe devrait se débarrasser immédiatement de cette norme.

En d'autres termes, le système de gestion des modifications est le lieu idéal pour assurer la traçabilité des exigences à la modification du code, et le contrôle de source peut fournir un historique détaillé des modifications en effectuant un écart entre les versions. Lorsque le code source est enregistré, le ticket de gestion des modifications correspondant est noté. Lorsqu'un ticket CM est résolu, nous notons quels fichiers de code source ont été modifiés. Je pense que cela fournit une référence croisée suffisante pour la traçabilité souhaitée.

J'aimerais savoir si quelqu'un n'est pas d'accord avec mon argument. Me manque-t-il certains avantages de l'historique du code source commenté que les systèmes de gestion des modifications et de contrôle des sources ne peuvent pas fournir?

Answer 1

Pour ma part, j’ai toujours trouvé que de tels commentaires étaient plus problématiques qu’ils ne valaient la peine: ils peuvent provoquer des conflits de fusion, peuvent apparaître comme des "faux positifs" lorsque vous essayez d’isoler les différences entre deux versions et Les modifications du code de référence qui ont depuis été obsolètes par des modifications ultérieures.

Il est souvent (pas toujours, mais souvent) possible de changer de système de contrôle de version sans perdre de métadonnées. Si vous deviez déplacer votre code vers un système non compatible , il ne serait pas difficile d'écrire un script permettant de convertir l'historique des modifications en commentaires avant la transition.

Answer 2

Un commentaire vous permet de trouver toutes les modifications et leurs raisons dans le code, là où elles sont pertinentes, sans avoir à fouiller dans les subtilités de diffs et du système de contrôle de version. De plus, si vous décidez de changer de système de contrôle de version, les commentaires resteront.

J'ai travaillé sur un grand projet avec une pratique similaire qui avait changé de système de contrôle de source à deux reprises. Il n’ya pas eu un jour où je n’étais pas content d’avoir ces commentaires.

Est-ce redondant? Oui. Est-ce inutile? Non.

Answer 3

J'ai toujours pensé que le code devrait bien entendu être sous contrôle de version et que le code source actuel (celui que vous pouvez ouvrir et lire aujourd'hui) devrait être valide. uniquement au présent .

Peu importe qu'un rapport puisse comporter jusqu'à 3 axes dans le passé et le mois dernier, vous l'avez mis à jour pour prendre en charge jusqu'à 6 axes. Peu importe si vous développez une fonction ou corrigez un bogue, à condition que la version actuelle soit facilement comprise. Lorsque vous corrigez un bogue, laissez simplement le code corrigé.

Il existe cependant une exception. Si (et seulement si) le code fixe vous semble moins intuitif que le précédent, incorrect; si vous sentez que quelqu'un pourrait venir demain et que, rien qu'en lisant le code, vous pourriez être tenté de le modifier de nouveau en ce qui semble "plus correct", il est bon d'ajouter un commentaire: "Ceci est Ainsi fait pour éviter ... bla bla bla. " Aussi, si le problème derrière est une histoire de guerre infâme au sein de la culture de l'équipe, ou si pour une raison quelconque la base de données de rapports de bogues contient des informations très intéressantes sur cette partie du code, je n’aurais pas trouvé incorrect d’ajouter "(voir ID de bogue 10005)" au commentaire explicatif.

Answer 4

Celui qui me préoccupe le plus est le fournisseur lockin. Si vous vous écartez de Rational, vous devez vous assurer que l'historique complet des modifications a été conservé pendant la migration, pas seulement la version des artefacts.

Answer 5

Lorsque vous êtes dans le code, vous devez savoir pourquoi il est structuré de la sorte, donc dans les commentaires de code. Les outils qui ne relèvent pas du code, aussi bons soient-ils, nécessitent trop de changements de contexte dans votre cerveau pour être utiles. En plus de cela, essayer de faire de l'ingénierie inverse du code de la documentation et un diff est assez difficile, je préférerais lire un commentaire tous les jours.

Answer 6

Il y avait une phase dans le code sur lequel je travaille, à partir de la période 1994-1996, où il y avait une tendance à insérer des commentaires d'historique des modifications en haut du fichier. Ces commentaires sont maintenant inutiles et inutiles, et l’un des nombreux nettoyages standard que j’effectue lors de la modification de fichiers contenant de tels commentaires consiste à les supprimer.

En revanche, il existe également des commentaires avec un numéro de bogue à l’emplacement où le changement a été effectué, expliquant généralement pourquoi le code ridicule est tel qu’il est. Ceux-ci peuvent être très utiles. Le numéro de bogue vous permet de chercher des informations ailleurs et de toucher le coupable (ou la victime - cela varie).

D'autre part, des articles comme celui-ci - authentiques; nettoyé la semaine dernière - faites-moi serrer les dents.

    if (ctab->tarray && ctab->tarray[i])
#ifndef NT
      prt_theargs(*(ctab->tarray[i]));
#else
      /* Correct the parameter type mismatch in the line above */
      prt_theargs(ctab->tarray[i]);
#endif /* NT */

L'équipe NT a bien répondu à l'appel. pourquoi ils pensaient que c'était une solution spécifique à la plate-forme, ça me dépasse. Bien sûr, si le code avait utilisé des prototypes au lieu de déclarations sans paramètre auparavant, l'équipe Unix aurait également dû réparer le code. Le commentaire a été une aide - en m'assurant que le bogue était authentique - mais exaspérant.