Stratégies de documentation sur la conception architecturale

Question

J'essaie de documenter un projet logiciel jusqu'à la phase actuelle. Le lectorat impliquerait moi-même (dans un futur proche), d'autres développeurs (actuellement et dans un avenir à court terme), ainsi que des utilisateurs finaux. Par conséquent, la documentation contient des descriptions des exigences de conception, de l'architecture/conception (structures de données, architecture, interface utilisateur, conception de la procédure), de la documentation technique et des instructions de l'utilisateur final. La documentation est principalement produite afin de fournir un certain historique. Actuellement, il s'agit d'une équipe de 2 personnes travaillant sur le projet, bien que cela pourrait impliquer plus de gens dans un futur proche car plus de fonctionnalités des projets d'autres personnes sont ajoutées à ce projet.

Ce que j'ai de la difficulté, c'est avec la documentation sur la conception architecturale (http://en.wikipedia.org/wiki/Design_document). Bien que j'aie essayé d'utiliser doxygen pour créer un type de diagramme de flux de données, cela n'a pas été facile. Existe-t-il des outils qui facilitent la génération de diagrammes de flux de données à partir du code C++ ou s'agit-il d'un dessin manuel sur Microsoft Visio? Merci d'avance.

Answer 1

Tous les diagrammes de bas niveau générés automatiquement à partir du code source seront inutiles. Ils seront plus obscur que votre code, ont une disposition visuelle désordonnée, et seront bientôt périmés. Les futurs développeurs se méfieront d'eux et regarderont le code à la place, il est donc préférable de déployer des efforts supplémentaires pour refactoriser votre code source (par exemple, utiliser des noms explicites, avoir une structure de classe qui représente votre domaine correctement, etc. sur).

Il est utile de créer de bons commentaires javadoc ou doxygen et de les tenir à jour: beaucoup de gens trouvent cela très utile.

Les diagrammes de haut niveau sont également utiles. Lisez le UML Distilled de Martin Fowler et apprenez la notation UML. Ensuite, utilisez Viso ou un autre éditeur graphique pour documenter uniquement les parties de votre logiciel qui seraient utiles pour les futurs développeurs. Ne perdez pas de temps à rendre les diagrammes "complets" et parfaits, concentrez-vous sur ce qui aidera le plus les autres développeurs.

Answer 2

Vous pouvez télécharger une version d'évaluation de Visual Studio Team Suite qui inclut les composants de l'édition de l'architecte.

Answer 3

Avant qu'un outil puisse documenter votre code, il devrait le lire. La lecture de votre code est également connue sous le nom de «reverse engineering».

Le code peut être réorienté par divers outils, qui peuvent ensuite créer des diagrammes UML de ce code. Malheureusement, quand j'ai essayé cela il y a seulement quelques années, j'ai trouvé que certains outils, qui font un excellent travail de reverse engineering C#, font un travail imparfait en reverse engineering C++ (car C++ est plus difficile à analyser et prend en charge -OO fonctions globales, etc.).

Encore vous pouvez trouver beaucoup d'outils en utilisant Google avec les termes "reverse engineering" ou "roundtrip" avec "C++" et "UML" ou "diagramme".

Microsoft a promis des outils C++ améliorés, mais je ne sais pas quel est le calendrier pour cela.