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


9

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.


Faites-vous référence aux emplacements spécifiques des méthodes incluses ou des commentaires sommaires du haut du fichier? Dans ce dernier cas, vous pouvez utiliser le style JavaDoc "#".
arin

J'ai généralement fait référence au fichier et à la méthode ("Avis dans le fichier ABC dans la méthode XYZ tel ou tel se produit") mais je suis curieux de voir quelles réponses arrivent.
Michael Itzoe

7
Ne serait-il pas plus judicieux dans ces cas de simplement mettre les commentaires dans le code réel?
Robert Harvey

Y a-t-il quelqu'un dans l'équipe qui pourrait examiner votre documentation et fournir des commentaires?
moucher

En avoir besoin, cela ressemble beaucoup à des effets secondaires dans d'autres méthodes que vous utilisez explicitement.
Michael Shaw

Réponses:


1

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.


Merci pour les commentaires! Je pense que «décrire son contexte» semble être la meilleure option pour moi. Merci encore.
loneboat

2
Avoir un problème unique signifie souvent que vous faites quelque chose de mal.
Thijs van Dien

2
@ThijsvanDien: Croyez-moi, nous faisons BEAUCOUP de choses dans le mauvais sens ici! ;-)
loneboat

3

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.


1
Cette réponse devrait être gagnante, sauf pour le point d'origine du PO selon lequel il quitte le projet et a probablement un temps limité et ne devrait pas non plus introduire de changement à sa sortie. Mais absolument correct - si quelque chose est suffisamment complexe pour supporter une référence externe, mettez-le dans sa propre unité de code nommée.
Ross Patterson

2

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.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.