Visual Studio Hacks

271

Chapter 8

CHAPTER EIGHT

Comments and

Documentation

Hacks 68–72

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 contin-

ues during the process of creating that application. A large part of docu-

menting 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 num-

ber 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 ...