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