Selfelected

Xml comment check

In C#/VBNet there is a nifty thing called Xml comments.  I always use it to explain my methods and classes.  A good thing about Xml comments is that they pop up as intellisense.  Press ctrl-J in Visual studio at your method call and your comments are shown.  The comments survive project boundaries so your well crafted comments in the business layer pop up at the presentation method calls to aid the GUI programmers.

The comments don’t travel C#->VBNet though.

In VBNet you get squiggly lines when the method call and the Xml comment don’t match.  In C# you have to go through the Analyze->Run code analysis to get the differences.

There are more comments on commenting here and here.

A tip for writing Xml comments in Csharp

There is something called xml comments in the dotnet world.

It looks something like

/// <summary>
///
/// </summary>
/// <param name=”name”></param>
/// <returns></returns>
public User FindUser( string name )
{…

The trick here is to write the comments on the very first line. Like:

/// <summary>This method finds and returns a User by its name.
/// </summary>
/// <param name=”name”></param>
/// <returns></returns>
public User FindUser( string name )
{…

When the code is folded it then looks like

/// <summary>This method finds and returns a User by its name. …
public User FindUser( string name )…

Visual Studio “suggests” writing the comments on line two, like

/// <summary>
/// This method finds and returns a User by its name.
/// </summary>
/// <param name=”name”></param>
/// <returns></returns>
public User FindUser( string name )
{…

but then after folding it looks like

/// <summary> …
public User FindUser( string name )…

(this is not a problem in vbnet)

More commenting comments are found here and here.

How to write xml comments in c#

My prefered way to write XML comments in C# is to write the first sentence on the first row like this:

/// <summary>This method does nothing.
/// <summary/>
public void Foo()
{
//NOP.
}

because when one folds the code (ctrl-m-o) one can see the first row like this:

/// This method does nothing. …
public void Foo() …

This is not an issue in vbnet.

To create a document out of this use Sandcastle which takes over after nDoc which is discontinued.

More comments on commenting are found here and here.