A big part of developing a high-quality application is properly documenting that application. Documentation starts during the design process with your design documents (UML diagrams, use cases, stories, etc.) and then continues during the process of creating that application. A large part of documenting an application you are developing is correctly commenting it. Good comments are even more important with the .NET Framework because you can generate documentation based on your comments.
Two types of comments can be used with the .NET Framework. The most common type is line comments (whenever you use // with C# or ' with VB.NET to mark a line as a comment). This type of comment is usually used to explain what the current or next line of code is doing. While these types of comments are very valuable (and I would hate to try and understand an application with none of these), the focus of this chapter will be on another type of comment, XML comments. These comments document a class or method using a piece of XML. The comments can then be used for a number of different things, not least of which is generating API documentation for your application. Here is an example of XML comments applied to a C# method:
/// <summary>
/// This method accepts a string and then
/// displays that string using a message box
/// </summary>
/// <param name="textToDisplay">The string to display</param>
private void HelloWorld(string textToDisplay)
{
MessageBox.Show(textToDisplay);
}To use XML comments with VB.NET, you have to do a little more work [Hack #70] .
The hacks in this chapter will cover how to get the most out of XML comments, how to create comments faster using an add-in, how to create documentation from your comments, how to use XML comments with VB.NET, and how to integrate your own documentation into Visual Studio.