Skip to Main Content
Visual Studio Hacks
book

Visual Studio Hacks

by James Avery
March 2005
Intermediate to advanced content levelIntermediate to advanced
304 pages
19h 23m
English
O'Reilly Media, Inc.
Content preview from 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. ...
Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.
Start your free trial

You might also like

Microsoft Visual Studio 2015 Unleashed, Third Edition

Microsoft Visual Studio 2015 Unleashed, Third Edition

Mike Snell, Lars Powers
.Net Framework Essentials

.Net Framework Essentials

Thuan L. Thai, Hoang Lam
C# 5.0 Unleashed

C# 5.0 Unleashed

Bart De Smet
Programming .NET Security

Programming .NET Security

Adam Freeman, Allen Jones

Publisher Resources

ISBN: 0596008473Errata Page