Meilleure façon d'ajouter de la documentation de développeur à vos projets Visual Studio
En gros, la question est la suivante: Où (et dans quel format) dois-je stocker la documentation textuelle pour le développeur associée à mes projets Visual Studio?
Pour élaborer: les commentaires XML sont intéressants, mais ils ne couvrent pas tous les cas d'utilisation. Parfois, vous souhaitez décrire l'architecture de classe du projet à un niveau élevé, ajouter des notes d'utilisation à votre bibliothèque ou tout simplement laisser un autre type de message aux futures générations de développeurs travaillant sur ce projet.
J'aimerais ajouter ces documents directement sous forme de fichiers dans le projet Visual Studio, afin de garantir (a) qu'ils soient disponibles pour le développeur sans autre recherche et (b) qu'ils soient sous contrôle de version (en utilisant le même référentiel svn/git/comme code source).
Actuellement, j'ajoute un dossier _Documentation au projet et utilise des fichiers texte, mais je ne suis pas sûr que ce soit la meilleure solution. Visual Studio n'a pas d'option pour le texte automatiquement recouvert de texte1, et fixer manuellement les sauts de ligne après chaque changement est ennuyeux. Par contre, les documents Word ne fonctionnent pas bien avec le contrôle de version et TeX est trop compliqué à configurer et à enseigner sur chaque PC développeur.
Existe-t-il une meilleure pratique bien établie pour cela?
1 Je sais qu’il existe Edition/Avancé/Word-Wrap, mais cela n’affecte que l’affichage, pas le fichier lui-même.
Je viens d'avoir le même problème - seulement j'ai remarqué que je pouvais ajouter un fichier HTML. Une fois ouvert, basculez simplement sur "Design" en bas de l'écran. Vous voudrez peut-être changer Build Action de 'Content' à 'None'
S'agissant d'un document HTML codé en dur, il est également possible d'utiliser des images en ligne (par exemple, un diagramme).
Aussi pour mes besoins (guide de programmation, description de l'architecture. Exemples d'utilisation de la base de données), j'ai choisi de créer un projet séparé (_Documentation) en tant que Windows Forms , car cela me permettra (ou à un nouveau programmeur) de disposer d'un exemple .
J'utilise GhostDoc (add-on de Visual Studio) pour la documentation de mon projet en ajoutant des classes, des méthodes, des propriétés, etc.: http://visualstudiogallery.msdn.Microsoft.com/46A20578-F0D5-4B1E-B55D-F001A6345748
Vous avez la possibilité, dans les commentaires XML, d'inclure un grand nombre de données que vous pouvez ensuite extraire avec un outil tel que Sandcastle (site) et de les transformer en un site de référence de style MSDN.
J'ai tendance à utiliser cette méthode et à écrire de longs commentaires XML (balises de commentaires MSDN) (le cas échéant) en utilisant le <para></para> pour générer des paragraphes et expliquer les modèles, les raisons commerciales ou les informations architecturales nécessaires aux futurs modificateurs/développeurs. Je l'utilise aussi pour donner des exemples d'utilisation.
Un bon lot de tests (bien écrit et bien nommé) peut aussi vraiment éclairer le but du code, en agissant comme une spécification.
J'espère que cela pourrait être un peu informatif dans vos recherches :)
Les commentaires XML conviennent mieux à la documentation de la méthode et non à l'écriture d'un contenu conceptuel long. Les commentaires XML longs pourraient nuire à la lisibilité du code.
J'ai aimé la fonctionnalité de documentation conceptuelle de Sandcastle, nous pouvons créer et stocker une documentation conceptuelle, qu'elle soit fonctionnelle ou liée à l'architecture, et la fusionner avec la documentation Code (commentaires XML). Les annotations que vous pouvez utiliser pour rédiger les sujets conceptuels sont extensibles, ce qui signifie que nous pouvons même adhérer aux modèles Enterprise.