Visual Studio Hacks

Create Comments Faster #69

Chapter 8, Comments and Documentation

|

281

HACK

/// <summary>

///

/// </summary>

/// <param name="htmlProvider"></param>

public void AppendHtmlText(HtmlProvider htmlProvider)

{

...

}

You would then add your text, so the XML documentation comment could,

for example, look something like this:

/// <summary>

/// Appends the HTML text of the specified provider.

/// </summary>

/// <param name="htmlProvider">The HTML provider.</param>

public void AppendHtmlText(HtmlProvider htmlProvider)

{

...

}

This is a typical method that comes by the dozen: the method name pretty

much says what it is doing and you definitely do not need much imagina-

tion to write the comment—after some time, these methods become a real

drain to document. On the other hand, you simply have no choice. If you

want the benefits of XML documentation comments (perhaps a nice help

file generated by NDoc

[Hack #71]), you have to comment all public (and pro-

tected) members, period.

Let’s take a closer look at the earlier example. The method is written accord-

ing to Microsoft’s Design Guidelines for Class Library Developers; some of

these rules are:

• Identifier names consisting of multiple words are written in Pascal-

Casing (the method name) or camelCasing (the parameter name).

• Acronyms are treated like normal words and are formatted accordingly

(for example, “Html” instead of “HTML”).

• Identifier names do not contain abbreviations. ...