Comment faire référence à des domaines spécifiques du code dans la documentation?

Je suis sur le point de quitter un projet, et avant de partir, mon patron m'a demandé de documenter le code (je n'ai pas très bien documenté). Ce n'est pas grave, le projet n'est pas terriblement complexe. Mais je trouve des endroits dans ma documentation où je voudrais dire: "Remarquez en ligne XYZ que tel ou tel se produit."

Dans ce cas, il n'est pas logique de faire référence à un numéro de ligne spécifique, car l'ajout ou la suppression d'une seule ligne de code surpasserait immédiatement la documentation. Existe-t-il des meilleures pratiques pour faire référence à une ligne de code spécifique sans y faire référence par numéro de ligne?

J'ai envisagé de joncher le code de commentaires comme:

/* linetag 38FECD4F */

Où "38FECD4F" est une balise unique pour cette ligne spécifique. Ensuite, je peux mettre dans la documentation, "Sur la ligne étiquetée '38FECD4F', notez que tel ou tel se produit."

D'autres idées? Je pense qu'il est généralement préférable de documenter les unités de code dans leur ensemble, plutôt que des parties spécifiques d'entre elles, mais dans le cas de ce projet particulier, il existe de LONGUES andains de code procédural, qui n'ont jamais été refondus en unités plus petites.

Si je comprends bien, vous semblez avoir un problème unique. Ce que vous voulez faire, c'est faire référence à une ligne de code spécifique dans les commentaires qui sont écrits dans une autre partie du même code.

Je ne rencontre généralement pas de tels scénarios où je dois faire référence à une ligne exect # dans certains commentaires écrits ailleurs - généralement le code est documenté là où il est écrit.

Je ne connais pas de moyen standard de le faire - mais au-dessus de ma tête ...

Vous pouvez vous référer à des portions de code via son contexte - c'est-à-dire les choses qui les entourent.

Notez au-dessus de la définition de func1 () que tel ou tel se produit

Notez que juste après la boucle for qui itère sur recordXYZItr, nous appelons également la méthode gc ()

Attention: Dans la méthode yahoo (), juste après la déclaration de la variable PQ, nous échangeons également les valeurs dans A et B, donc l'objet mapABC doit également être copié

Une autre façon consiste à ajouter des balises descriptives. Au lieu de quelque chose comme 38FECD4F, vous pouvez dire Some XYZ implementationou BUGFIX 1474, puis vous référer à cela ailleurs.

Cela dépend beaucoup de la façon dont le code a été écrit, et je comprends que cela peut induire un tas de refactoring que vous n'êtes pas ici pour faire.

Mais ... si vous avez besoin de faire référence à une ligne de code spécifique comme une unité entière, cela ne signifie-t-il pas que son code représente une opération abstraite et pourrait donc être refactorisé dans sa propre méthode / fonction? Une fois que c'est dans une méthode, c'est assez facile, il suffit de se référer à namespace.class.methodBien sûr, cela signifie avoir des méthodes très petites, environ 5-10 lignes de long ou même moins. Avec Doxygen, vous pouvez mettre la documentation au-dessus de la méthode, et elle resterait toujours synchronisée avec le nom de la méthode / classe / espace de noms.

Je vous suggère d'adopter une approche différente, autre que la liaison d'une documentation externe au code au code:

1. ajoutez des commentaires à votre code, à l'aide d'un outil comme doxygen .

2. s'il est nécessaire d'expliquer un concept plus en détail que ce qui est approprié dans la documentation du code (nouvellement créé), vous pouvez toujours créer un document distinct et le lier à celui-ci.

De cette façon, vous pouvez facilement générer la documentation sous forme de page Web ou de PDF, et elle reste cohérente avec le code. L'utilisation de certaines étiquettes artificielles deviendra très difficile à maintenir et encore plus difficile à comprendre pour les non-initiés.