Best Practice on C# Code Commenting

For the next 30 minutes I recommend you do the following 7 steps. They'll teach you how to become proficient on a best practice for self-documenting your C# code in projects done using Microsoft Visual Studio. The same lessons apply for other .NET languages but I mention C# because its the most popular one. Once you've learned this process I'm confident you will use it for now on because it automates the documentation process for all development work to allow you to build HTML/Help files on-the-fly. Make sure you have Visual Studio 2005 or later installed on your workstation and that you've been able to successfully create and build a solution/project before proceeding with these steps.

(1) Read http://www.winnershtriangle.com/w/Articles.DocumentingCSharpSourceCode.asp which is an excellent intro to C# Code Commenting.

(2) Read http://www2.sys-con.com/ITSG/virtualcd/Dotnet/archives/0108/horan/index.htm for a nice explanation on code commenting.

(3) Run Visual Studio, open a solution/project and follow the following instructions. (a) Open the property page for the project, usually by right-clicking on the project in the Solution Explorer, and click Properties. (b) After the dialog has opened, click the Configuration Properties folder. (c) Click the Build option. (d) In the right pane, there will be a property field called XML Documentation File. Set this to the path and file name of the desired file. The path entered is relative to the project directory, not absolute. (e) Put some "Hello World" text in a summary tag on at least one class/member within the project. (f) Build the project and view the XML Documentation File to see your "Hello World" text. (source: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx)

(4) Download http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en and install the product. If you skip this step then you will be very sorry.

(5) Go to http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx, download the latest "Sandcastle Help File Builder Installer" MSI file and install. Then run it on your desktop start menu as follows: "All Programs -> Sandcastle Help File Builder". In the GUI click the ADD button to include the DLL file that corresponds with the assembly you generated in Step (3)(f) of this tutorial. Then select "Documentation -> Build Project" from the menu to build a Help file. Finally select "Documentation -> View Help File" from the menu to see the help file and search for your "Hello World" text.

(6) Read http://msdn.microsoft.com/en-us/library/5ast78ax(VS.71).aspx on recommended documentation tags and try them out in the project you used in Step 3. Build the project in Visual Studio. Then build the help file in Sandcastle to see the resulting help file.

(7) Read http://www.csharpfriends.com/statics/tools.aspx to see some other code commenting tools for .NET. However I recommend using Sandcastle because it has plenty of functionality, its source code is freely available at http://www.codeplex.com/Sandcastle/SourceControl/ListDownloadableCommits.aspx and a google search such as http://tinyurl.com/sand-code-doc shows that there is sufficient documentation, assistance and community support for Sandcastle's future.

Did you do all 7 steps and bookmark this link for future reference? If so then you should now be sufficiently proficient enough on the current best practice for self-documenting your C# or VB.Net code in projects done using Microsoft Visual Studio. Congratulations Guru!! See http://alex-tfs.blogspot.com/2009/01/read-httpalex-tfs.html for ideas on enhancing this best practice.