Thursday, September 4, 2008

Source Code Comments

In computer programming, a comment is a programming language construct used to embed information in the source code of a computer program.

According to Jeffrey Kotula,"Source code documentation is a fundamental engineering practice critical to efficient software development. Regardless of the intent of its author, all source code is eventually reused, either directly, or just through the basic need to understand it. In either case, the source code documentation acts as a specification of behavior for other engineers. Without documentation, they are forced to get the information they need by making dangerous assumptions, scrutinizing the implementation, or interrogating the author. These alternatives are unacceptable. Although some developers believe that source code "self-documents", there is a great deal of information about code behavior that simply cannot be expressed in source code, but requires the power and flexibility of natural language to state. Consequently, source code documentation is an irreplaceable necessity, as well as an important discipline to increase development efficiency and quality."(For more quotes click here).


C# offers several XML tags that can be placed directly within your source files to document the code, and Microsoft documents these tags very nicely in Visual Studio .NET help files. Once the developer has documented her source using the XML tags, she can use Sandcastle to produce integrated .chm files that contain the source documentation.


Although the description above and in the article may use the term ‘comment’, the XML tags are used to produce external source documentation. This differs from traditional code comments in that the realized documentation can be distributed as API (Application Programmer’s Interface) documentation. (For more details refer here.)


The following information outlines what you need to install so you can create proper Inline API (MSDN-style) documentation. Here is a list of programs you need to install.

Sandcastle

Sandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandcastle has the following key features

* Works with or without authored comments* Supports Generics and .NET Framework 1.1, 2.0, 3.0, 3.5 and other released versions of Framework* Sandcastle has 2 main components (MrefBuilder and Build Assembler)* MrefBuilder generates reflection xml file for Build Assembler* Build Assembler includes syntax generation, transformation, etc* Sandcastle is used to build Microsoft Visual Studio and .Net Framework documentation.

You can download it from CodePlex http://www.codeplex.com/Sandcastle

SHFB (Sandcastle Help File Builder)

SHFB is a GUI interface that almost looks identical to the NDoc interface so anyone familiar with NDoc should be quite comfortable using it. It uses the underlining Sandcastle API to generate an HTML 1.x (.CHM) file, an HTML 2.x (.HxS) file, and/or a web site.

You can download SHFB from CodePlex http://www.codeplex.com/SHFB

DocProject for 2008

DocProject drives the Sandcastle help generation tools using the power of Visual Studio 2005/2008 and MSBuild. Choose from various project templates that build compiled help version 1.x or 2.x for all project references. DocProject facilitates the administration and development of project documentation with Sandcastle, allowing you to use the integrated tools of Visual Studio to customize Sandcastle's output.

You can download DocProject from CodePlex http://www.codeplex.com/DocProject

No comments: