Comment Your Code As You Develop With GhostDoc

Introduction

I have spoken to a number to people over the years when it comes to documenting code and I was surprised to hear the answers. I can tell you that I favor documentation and the time when the code is being written and not accepting the intention that once will come back later to complete the task. Stop and think about it for a moment. How many times have you sat down to a project and realized that there was not documentation and when you ask that question “Where is the documentation?” your manager looks at you and painfully makes you aware there is none. From my point of view documentation of the code makes us all much more efficient and at the same time benefits your clients since time to delivery can be decreased in most cases. This is especially true as you development team changes over time. If we look at documentation as a integral part of software development it becomes a standard and we all know how well the use of standards serve us whereas the lack of standards promotes confusion and short-cuts.

Comments Explained

The first step you should take is to become familiar with the XML tags used in the documentation process. As a developer I prefer C# over VB.NET and the way in which comments are accomplished differ in these languages.

The following list outlines the various XML comments that C# supports. [ Reference: MSDN ]

<c> gives you a way to indicate that text within a description should be marked as code.
<code> gives you a way to indicate multiple lines as code.
<example> allows example usage to be embedded in the comments.
<exception> documents the exceptions associated with the code.
<include> is used to include documentation from other files.
<list> to define the heading row of either a table or definition list.
<para> is for use inside a tag, such as <summary>, <remarks>, or <returns>, and lets you add structure to the text.
<param> documents a method parameter.
<paramref> gives you a way to indicate that a word in the code comments, for example in a <summary> or <remarks> block refers to a parameter. The XML file can be processed to format this word in some distinct way, such as with a bold or italic font.
<permission> defines access permissions for a member.
<remarks> provides a description of a class/method.
<returns> describes the return value.
<see> lets you specify a link from within text.
<seealso> lets you specify the text that you might want to appear in a See Also section.
<summary> provides a summary of the item.
<typeparam> should be used in the comment for a generic type or method declaration to describe a type parameter.
<typeparamref> Use this tag to enable consumers of the documentation file to format the word in some distinct way, for example in italics.
<value> describes a property.

The following list outlines the various XML comments that VB.NET supports. [ Reference: MSDN ]

<c> gives you a way to indicate that text within a description should be marked as code.
<code> gives you a way to indicate multiple lines as code.
<example> allows example usage to be embedded in the comments.
<exception> documents the exceptions associated with the code.
<include> is used to include documentation from other files.
<list> to define the heading row of either a table or definition list.
<para> is for use inside a tag, such as <summary>, <remarks>, or <returns>, and lets you add structure to the text.
<param> documents a method parameter.
<paramref> gives you a way to indicate that a word in the code comments, for example in a <summary> or <remarks> block refers to a parameter. The XML file can be processed to format this word in some distinct way, such as with a bold or italic font.
<permission> defines access permissions for a member.
<remarks> provides a description of a class/method.
<returns> describes the return value.
<see> lets you specify a link from within text.
<seealso> lets you specify the text that you might want to appear in a See Also section.
<summary> provides a summary of the item.
<typeparam> should be used in the comment for a generic type or method declaration to describe a type parameter.
<value> describes a property.

Now that you have this knowledge and I am sure that you will never forget any of this it is time to document your code. Wait a minute, if you are anything like I am there is no way you will remember every comment attribute and even if you did it still comes down to time a a manual process when it comes to documentation. Of course Microsoft has done a good job with IntelliSense and studding out a comment but you still must enter the details by hand and this is time consuming but again one of those necessary evils if we are to be successful.

Take a look at the following examples, while they are simple in nature the provide the necessary insight into the overall benefit of code documentation.

Bad:


public static void SendEmail(SmtpSettings smtpSettings, string from,
string to, string cc, string bcc, string subject, string messageBody,
bool html, string priority)
{
string replyTo = string.Empty;
SendEmail(smtpSettings, from, replyTo, to, cc, bcc, subject,
messageBody, html, priority);
}

Good:


/// <summary>
/// Sends the email.
/// </summary>
/// <param name="smtpSettings">The SMTP settings.</param>
/// <param name="from">From.</param>
/// <param name="to">To.</param>
/// <param name="cc">The cc.</param>
/// <param name="bcc">The BCC.</param>
/// <param name="subject">The subject.</param>
/// <param name="messageBody">The message body.</param>
/// <param name="html">if set to <c>true</c> [HTML].</param>
/// <param name="priority">The priority.</param>
public static void SendEmail(SmtpSettings smtpSettings, string from,
string to, string cc, string bcc, string subject, string messageBody,
bool html, string priority)
{
string replyTo = string.Empty;
SendEmail(smtpSettings, from, replyTo, to, cc, bcc, subject,
messageBody, html, priority);
}

GhostDoc To The Rescue

GhostDoc is a tool I have used for years which was developed by Roland Weigelt. GhostDoc has recently been picked up by SubMain which still provides this tool free of charge. For the specific details be sure to read The Future of GhostDoc. This tool leaves an extremely low footprint on your system however makes short work when it comes to documentation. Once you download and install GhostDoc you will find it under the Tools menus with the Visual Studio IDE.

ghostdoc tools 1 31 Comment Your Code As You Develop With GhostDoc

One of the biggest features is the ability to export and share rule sets with you fellow team members. To do this simply click “Configure GhostDoc” and you will be presented the following:

ghostdoc tools 2 31 Comment Your Code As You Develop With GhostDoc

At the bottom left hand side of the screen click “Export” and send the rules out via email or even place them on a network drive. Now the entire team can quickly and efficiently generate documentation. I suppose the last question remaining is how do I now document my code with this tool. Well, the answer is two easy clicks of the mouse and your done! Right click on the method you wish to document and select “Document this”.

ghostdoc tools 3 31 Comment Your Code As You Develop With GhostDoc