Méthodologie pour documenter la base de code existante

Je travaille en équipe sur une application existante dépourvue de documentation en ligne et de documentation technique. Pendant que je travaillais sur divers rapports de bogues sur l'application, j'ai écrit une sorte de fil d'Ariane - des numéros de bogues à divers endroits afin que le prochain développeur puisse se référer à ce numéro de bogue pour voir ce qui se passait.

Ma question est donc:

Quelle est la méthode la plus efficace pour documenter ce code? Devrais-je documenter lorsque je touche la zone (la méthode du virus, si vous voulez), ou devrais-je documenter chaque section séparément et ne pas suivre les chemins qui se ramifient vers d'autres zones de l'application? Devrais-je insérer des commentaires en ligne là où ils n'existaient pas auparavant (avec la crainte de ne pas pouvoir identifier correctement le code)?

Quelle méthode utiliseriez-vous pour documenter avec précision et rapidité une application assez volumineuse ne contenant pas de documentation en ligne existante, ni de références en ligne à une documentation externe?

Documentation des anciennes bases de code

Je recommande fortement de suivre la règle de scout avec des bases de code héritées. Essayer de documenter un projet hérité indépendamment de travailler dessus ne se produira jamais.

Documentation en code

Le plus important est d’utiliser les installations de documentation dans l’environnement de développement choisi, c’est-à-dire pydoc pour python, javadoc en java ou commentaires xml en C #. Cela facilite la rédaction de la documentation en même temps que l’écriture du code.

Si vous comptez revenir et documenter des choses plus tard, vous ne le comprendrez peut-être pas, mais si vous le faites pendant que vous écrivez le code, alors ce qui doit être documenté sera frais dans votre esprit. C # a même la possibilité d'émettre un avertissement de compilation si la documentation XML est incomplète ou incompatible avec le code réel.

Tests en tant que documentation

Un autre aspect important est une bonne intégration et des tests unitaires.

Souvent, la documentation se concentre sur ce que les classes et les méthodes font de manière isolée, en ignorant comment elles sont utilisées ensemble pour résoudre votre problème. Les tests les mettent souvent en contexte en montrant comment ils interagissent les uns avec les autres.

De même, les tests unitaires soulignent souvent les dépendances externes de manière explicite au moyen desquelles des éléments doivent être simulés .

Je constate également que, grâce au développement piloté par les tests, j'écris un logiciel plus facile à utiliser, car je l'utilise dès le départ. Avec un bon framework de test, rendre le code plus facile à tester et à le rendre facile à utiliser est souvent la même chose.

Documentation de niveau supérieur

Enfin, il y a quoi faire au niveau du système et de la documentation architecturale. Beaucoup préconiseraient d'écrire une telle documentation sur un wiki ou d'utiliser Word ou un autre logiciel de traitement de texte, mais pour moi, le meilleur endroit pour une telle documentation est également à côté du code, dans un format de texte brut adapté au système de contrôle de version.

Comme avec la documentation intégrée au code, si vous stockez votre documentation de niveau supérieur dans votre référentiel de code, vous aurez plus de chances de la maintenir à jour. Vous bénéficiez également de l'avantage que lorsque vous extrayez la version XY du code, vous obtenez également la version XY de la documentation. De plus, si vous utilisez un format convivial VCS, cela signifie qu'il est facile de créer des branches, des différences et de fusionner, tout comme votre code.

Je préfère tout d’ abord , car il est facile de produire des pages html et des documents pdf à partir de celui-ci. Il est beaucoup plus convivial que LaTeX , mais peut quand même inclure des expressions mathématiques LaTeX quand vous en avez besoin.

Question piège. Fondamentalement, j'utiliserais la méthode de "refactoring", que je reformulerais comme "si vous touchez le code, documentez-le".

Mais pour être précis; au fur et à mesure que des problèmes se présentent et que vous devez vous familiariser avec le code pour corriger les bogues rencontrés, je dirais que vous devriez utiliser cette familiarité pour écrire des commentaires sur ce code en particulier; En substance, la motivation à corriger le bogue vous a forcé à vous familiariser suffisamment avec le code pour pouvoir le documenter. Et pour cette raison, je serais réticent à suivre des branches non liées OU à documenter des fonctions non liées, car à ce stade, si vous n’effectuez pas de test actif du code (pour vérifier votre correction de bogue), il est difficile d’être totalement certain que vous comprenez précisément ce que le code fait et pourquoi. (Je ne me lance pas dans la question selon laquelle il peut également être difficile de comprendre précisément quoi et pourquoi le code fait ce qu’il fait même lorsqu’on teste une correction de bogue; vous '

Cette approche devrait tendre à maximiser la précision, en sacrifiant la vitesse globale, sans toutefois affecter votre besoin de maintenir le code trop sévèrement en même temps. Bien sûr, si vos tâches de correction de bugs sont minimes, vous pouvez vous aventurer dans un "territoire inconnu" et commencer à documenter, mais si vous (comme la plupart d'entre nous) ne trouvons pas assez de temps dans la journée pour corriger le code et le documenter, ceci est un bon compromis.

Une chose à noter également; vous devriez avoir une bonne documentation externe. Vous dites que votre code ne contient aucune référence à une documentation externe; J'espère pour vous qu'une telle documentation externe existe, cependant. Sinon, je ferais de l'écriture de cette documentation externe votre première priorité; Je pense que quelque chose au niveau d'une spécification fonctionnelle est absolument critique pour tous les grands projets de logiciels. La raison en est que les spécifications fonctionnelles, ou la documentation de haut niveau de cette forme, peuvent aider à prévenir le "fluage des fonctionnalités" ou la "dérive des fonctionnalités" dans n’importe quel logiciel; et la dérive de fonctionnalités (en particulier) peut être destructrice pour la documentation car elle peut rendre la documentation obsolète. (Je définis le fluage des fonctionnalités comme l'addition progressive (et agaçante) de fonctionnalités à un logiciel; dérive de fonctionnalitésDe l’autre côté, c’est là que l’ensemble des actions prises par les logiciels évolue lentement dans le temps. Le fluage des fonctionnalités est ADDITIF, c'est-à-dire qu'il consiste généralement à augmenter l'ensemble des fonctionnalités du logiciel; En revanche, la dérive des entités est à somme nulle; Un par un, une fonctionnalité de bord est définie pour faire quelque chose de différent, jusqu'à ce que le logiciel fasse quelque chose de complètement différent de ce qui était initialement prévu. La dérive des fonctionnalités est rare, mais MORT pour la documentation.)

Une application que j'ai co-développée au cours des deux dernières années manquait cruellement de documentation. À un moment donné, il est devenu évident que nous allions transmettre l'application à un autre développeur qui allait la maintenir à partir de ce moment-là. Nous avons donc dû documenter le code.

Afin de gérer l'ampleur gigantesque du processus de documentation, j'essayerais de documenter tout le code dans une fonctionnalité spécifique ou une partie de l'application un jour donné. Je n'avais pas de modèle particulier, mais insistais pour en faire tous les jours et pour obtenir un sentiment de réussite en documentant quotidiennement un fichier complet ou une section de l'application.

Il a fallu des mois pour documenter l’ensemble de la demande, mais au bout d’une demi-heure (max) par jour, il n’a jamais vraiment mangé dans le calendrier du projet et a évité une bonne partie de l’ennui lié à la documentation.

Nous avons utilisé la documentation XML en C #, qui fournissait suffisamment de fonctionnalités et de structures pour rendre la documentation facile. Même si vous ne documentez pas une application C #, le schéma consistant à avoir d'abord un court résumé suivi de remarques était très utile.

Je documenterais comme j'ai ajouté / modifié le code. En dehors de cela, je documenterais également des API publiques ou des interfaces entre modules. Si vous documentez tout le code, vous ne verrez peut-être pas le retour sur investissement du temps passé. Il peut être utile d’utiliser quelque chose comme un wiki pour organiser la documentation externe au fur et à mesure que vous la développez. Le document le plus utile auquel j'ai fait référence au début de mon dernier projet était le document d'architecture. Il contenait des informations sur les technologies utilisées et fournissait une vue d'ensemble de la manière dont l'application était stratifiée.

Je voudrais utiliser les commentaires Doxygen. Doxygen a plus de formats de sortie que la plupart des autres formats libres et est simple à apprendre.

Vous pourriez même envisager de faire appel à un entrepreneur pour le faire, comme certains d'entre nous le font pour gagner leur vie. Cependant, avec ce choix, vous devez toujours vous engager à examiner les documents.

Une autre technique courante consiste à affecter le nouveau dev à la documentation du code. Demandez ensuite à chaque nouvelle personne de la parcourir à mesure qu'elle se met au diapason. Sachez que certains développeurs y voient un canal radiculaire, nécessaire uniquement dans les cas directs, LOL.

Avant de commencer à documenter quoi que ce soit, développez une norme. Cela peut être aussi simple que de s'assurer que vous écrivez quelques lignes au-dessus d'un en-tête de fonction ou de classe en quelque chose de plus officiel et verbeux (comme javadoc). Avant que quiconque puisse enregistrer du code, sa documentation doit respecter cette norme.

Ce que j’ai trouvé fonctionne bien, c’est d’ajouter des commentaires bien écrits avant l’en-tête de fonction aux fonctions précédemment non documentées que j’ai créées et d’ajouter des commentaires intégrés à tout ce que j’ai ajouté. Vous voulez éviter de documenter du code que vous n'avez pas touché. C'est pire d'avoir de mauvais commentaires que pas de commentaires, et si vous documentez ceci 'rapidement', vous écrirez probablement de mauvais commentaires.