Read http://alex-tfs.blogspot.com/2009/01/best-practice-on-c-code-commenting.html to see a tutorial I wrote on what I consider to be the current "best practice" for C# Code Commenting. I have a few suggestions on future improvements to this "Best Practice":
(1) There should be a way to automate adding a post-build event for source code projects to have the Sandcastle CHM generated as part of the build.
(2) Certainly other project documentation (such as project charters, requirements documents, design/architecture documents, TFS reports (i.e. builds, work items, changesets, etc.) and other artifacts can be integrated into the post-build event.
(3) Certainly the whole post-build process done locally on auto-building the CHM file and including other artifacts can be included as part of the TFS Build process.
(4) Certainly templates with the HP logo, SLM-labels, and other process needs can be integrated into the help-files generation process.
(5) Considering that code comments are compiled into a XML file using a defined schema we can always customize the documentation however we want with XSLT, third party tools, etc.
(6) As Sandcastle is "open source" and Visual Studio is quite extensible it should be possible to specify custom XML tags that can be processed to generate whatever output or perform whatever tasks we want done at build-time.
Do you have any suggestions to add?
Friday, January 2, 2009
Subscribe to:
Post Comments (Atom)
No comments:
Post a Comment