Commenting Source Code in .NET

In any project involving more than two developers you have to document the source code. All developers give an extreme laziness when it comes time to put into words the result of several hours, days or weeks of hard work.

But you have to get used to review the code to comment on everything thoroughly, so the next developer who must maintain or modify the code can understand perfectly without making debug the code. Believe me, he will be eternally grateful.

Another key aspect is to comment the classes, methods, attributes, etc, so that with a brief explanation about inputs, otuputs and what it do. This will allow our code is really a black box to the other developers on our team, and are certain they are using the proper method to get the result we want.
 
With .NET we don't have excuse for not doing so, as this administration is almost automatic. The steps are:

1 - Commenting members

Any language. NET has the option to generate documentation through comments with 3 slash (///) within the source code. Pressing key 3 times "/" over any member (class, method, attribute, etc) automatically. NET generates a code where you can enter data related to the member concerned.

 

All these comments will then be displayed on the Intelligence of Visual Studio when we access to the members.

2 - Generate documentation

 These comments are automatically stored in an XML file defined. Later we can generate documentation. The syntax is:

csc yourClass.cs /doc:yourDocumentation.xml 

This means you take all comments and stored in the XML file (for example "tuDocumentacion.xml").

Now, if we work with Visual Studio, we can say that when you build or compile, build your XML file automatically.

This is in Project Properties (Project no solution) -> Generate -> then you should select the box that says "XML documentation file" (note: you must put both Debug to Release).

There is also an Add-On for Visual Studio 2003, 2005 and 2008 called GhostDoc. This Add-On helps us to create the comments, only positioned on the member that want to generate your documentation and pressing the right, and selecting "Document this".

 

3 - Formatting the documentation

Once created our documentation, we provide a format for display.

There are several possibilities:

• Look like msdn, which is Web-like (eg array).
• Look like chm, which is the typical Windows Help

To do this you must download SandCastle which will generate msdn documentation, however, if you want to help generate files like windows style, or the CHM, you must also download HTML Help Workshop.

The only problem is that as Sandcastle has no graphical interface and the process is quite long, the creation of documentation is a bit complicated ... but peaceful there is(are) IDE (s) that abstract complexity. One of them is called SandCastleGUI. (I have test it and really is very easy).

I don't know in other languages as will be commenting source code. Is it as easy?