Code Documentation in .NET
 
Published: 18 Jul 2005
Unedited - Community Contributed
Abstract
Documenting your code in .NET is much easier than you might expect. In this article, Steven Swafford discusses the XML documentation tags recommended by Microsoft, and shows how to put these tags to use. By taking the time to document your code, not only will you and others be able to clearly understand the code and utilize features such as IntelliSense, you will also be able to employ third-party tools such as NDoc to generate professional-looking MSDN-style documentation. This article also looks at the value of well-documented code.
by Steven Swafford
Feedback
Average Rating: 
Views (Total / Last 10 Days): 50976/ 109

Introduction

As a developer, I myself have a very strong opinion that all code that is written should be documented. Documentation should always be foremost in your thought process. Why, you may ask? Well, let me explain. Have you ever been in a position where you were hired for a project, and there was absolutely no documentation whatsoever for anything that was written? I know from firsthand experience the headache that this can cause no matter which programming language is used. For example, what if you were tasked with changing the discount price on an item a consumer may purchase, and you then open the code only to find an in-depth process to calculate the discount, and there was not a single comment in the code? In this type of scenario, you must track down an individual who can provide the specific business rules for this process before you can begin to understand what the code is doing.

Documentation is a straightforward and simple process for C# and VB.NET. While C# XML documentation is supported in Visual Studio 2003 and above, developers who code in VB.NET have had to turn to alternative means when it came to documentation. While there are, in fact, a variety of products on the market that assist in overcoming this problem, the good news is that Visual Studio 2005 now supports VB.NET XML documentation inherently. I am sure that this will be a much-welcomed addition for VB.NET developers.

The goal of this article is to raise the awareness of code documentation and the importance of well-written documentation. I will also cover the specifics of writing documentation, and explain the benefits that you and other developers will experience from such documentation. I will not provide in-depth code examples; rather, I hope to stress the importance and benefits of documentation.

XML Tags Used for Documentation Comments

The first step you should take is to become familiar with the XML tags used in the documentation process. The following tags are a recommendation from Microsoft for the documentation comments. Keep in mind that these tags are only a recommendation. However, the tags listed below should prove to be valuable during the documentation process. You can also utilize any custom tag that is valid XML, as the compiler will process any such tag, and there are products out there that take advantage of this. One such product is NDoc, which I will discuss a little later.

Figure 1: Recommended XML Documentation Tags

Tag

Description

<c>

The <c> tag gives you a way to indicate that text within a description should be marked as code.

<code>

The <code> tag gives you a way to indicate multiple lines as code.

<example>

The <example> tag lets you specify an example of how to use a method or other library member.

<exception>

The <exception> tag lets you specify which exceptions can be thrown.

<include>

The <include> tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file.

<listheader>

The <listheader> block is used to define the heading row of either a table or definition list.

<para>

The <para> tag is for use inside another tag, such as <summary>, <remarks>, or <returns>, and lets you add structure to the text.

<param>

The <param> tag should be used in the comment for a method declaration to describe one of the parameters for the method. The text for the <param> tag will be displayed in IntelliSense, the Object Browser, and in the Code Comment Web Report.

<paramref>

The <paramref> tag gives you a way to indicate that a word is a parameter.

<permission>

The <permission> tag lets you document the access of a member.

<remarks>

The <remarks> tag is used to add information about a type, supplementing the information specified with <summary>. This information is displayed in the Object Browser and in the Code Comment Web Report.

<returns>

The <returns> tag should be used in the comment for a method declaration to describe the return value.

<see>

The <see> tag lets you specify a link from within text.

<seealso>

The <seealso> tag lets you specify the text that you might want to appear in a See Also section.

<summary>

The <summary> tag should be used to describe a type or a type member. Use <remarks> to add supplemental information to a type description. The text for the <summary> tag is the only source of information about the type in IntelliSense, and is also displayed in the Object Browser and in the Code Comment Web Report.

<value>

The <value> tag lets you describe a property. Note that when you add a property via code wizard in the Visual Studio .NET development environment, it will add a <summary> tag for the new property. You should then manually add a <value> tag to describe the value that the property represents.

MSDN: C# Programmer's Reference: Recommended Tags for Documentation Comments

 

Putting XML Tags to Use in the Code

Now that you have the foundation in place to utilize the XML tags recommended by Microsoft, let us now take a look at the SQLServerDAL class that is part of Microsoft .NET Petshop 3.0. The reason I have selected this class is because Microsoft has done a great job of documenting the ExecuteReader method.

Listing 1: C# Class Example XML Documentation

namespace PetShop.SQLServerDAL {


 /// <summary>
 /// The SqlHelper class is intended to encapsulate high performance, 
 /// scalable best practices for common uses of SqlClient.
 /// </summary>
 public abstract class SQLHelper {
  
  //Database connection strings
  public static readonly string CONN_STRING_NON_DTC =
ConnectionInfo.DecryptDBConnectionString(ConfigurationSettings.AppSettings["SQLConnString1"]);
  public static readonly string CONN_STRING_DTC_INV =
ConnectionInfo.DecryptDBConnectionString(ConfigurationSettings.AppSettings["SQLConnString2"]);  
  public static readonly string CONN_STRING_DTC_ORDERS =
ConnectionInfo.DecryptDBConnectionString(ConfigurationSettings.AppSettings["SQLConnString3"]);
  


  /// <summary>
  /// Execute a SqlCommand that returns a resultset against the database specified in the connection string 
  /// using the provided parameters.
  /// </summary>
  /// <remarks>
  /// e.g.:  
  ///  SqlDataReader r = ExecuteReader(connString, CommandType.StoredProcedure, "PublishOrders",
  ///       new SqlParameter("@prodid", 24));
  /// </remarks>
  /// <param name="connectionString">a valid connection string for a SqlConnection</param>
  /// <param name="commandType">the CommandType (stored procedure, text, etc.)</param>
  /// <param name="commandText">the stored procedure name or T-SQL command</param>
  /// <param name="commandParameters">an array of SqlParamters used to execute the command</param>
  /// <returns>A SqlDataReader containing the results</returns>
  public static SqlDataReader ExecuteReader(string connString, CommandType cmdType, string cmdText,
params SqlParameter[] cmdParms) {
   SqlCommand cmd = new SqlCommand();
   SqlConnection conn = new SqlConnection(connString);


   // we use a try/catch here because if the method throws an exception we want to 
   // close the connection throw code, because no datareader will exist, hence the 
   // commandBehaviour.CloseConnection will not work
   try {
    PrepareCommand(cmd, conn, null, cmdType, cmdText, cmdParms);
    SqlDataReader rdr = cmd.ExecuteReader(CommandBehavior.CloseConnection);
    cmd.Parameters.Clear();
    return rdr;
   }catch {
    conn.Close();
    throw;
   }
  }
  
 }

 

As you can see by the example code in Listing 1, the documentation comments for the ExecuteReader method have made use of the <summary>, <remarks>, <param>, and <returns> tags.

At this point you may be asking yourself, “What if I have written this class in VB.NET?” While it is true that in Visual Studio .NET XML documentation is supported in C# but not in VB.NET, there is a solution to overcome this obstacle: take a look at the VBCommenter PowerToy Development workspace. By utilizing this free plug-in, there is absolutely no reason why any developer who uses VB.NET should ever say, “I would document my code, however Microsoft has not provided the ability for me to do so.” To learn more about using this plug-in, read the MSDN article, Creating Documentation for Your Visual Basic .NET Application.

 

Figure 2: Generated Documentation From VB.NET Code

Credit: The above image is from the article Creating Documentation for Your VB .NET Application.

 

Figure 3: NDoc Documentation from C# Code

Credit: The above image was generated from the SQLServerDAL class using NDoc.

Following are five points that I personally feel should be taken into consideration when you begin to develop:

  1. Comments must add to the clarity of your code. The reason you document your code is to make it more understandable to you, your coworkers, and any other developer who comes after you.
  2. If your program is not worth documenting, it probably is not worth running.
  3. Avoid decoration, i.e., do not use banner-like comments.
  4. Keep comments simple. Some of the best comments I personally have ever seen are simple and straightforward.
  5. Write the documentation before you write the code. This gives you an opportunity to think about how the code will work before you write it and will ensure that the documentation is completed. But you should at least document your code as you write it.

At this point I have discussed the recommended XML document tags, provided a sample documented class, and presented the compiled help file. I hope that you agree that documentation is definitely a powerful and important process.

XML Documentation and the Payoff

As I stated previously, documenting your code adds clarity for you and others. The biggest payoff in my opinion comes with IntelliSense.

 

Figure 4: IntelliSense in Action

If you refer back to the example C# class in Listing 1, you will see now how the documentation that was written comes into play when you are working within the IDE. While some people may state that their development team is small and that there is simply not enough time to document each class, I beg to differ. Just imagine if the IntelliSense feature within Visual Studio .NET was not available and you had to consult the MSDN Library each time you came across something with which you were not familiar. Just imagine how much time a developer or group of developers would spend consulting the MSDN Library (and imagine if this documentation did not exist!).

Summary

I have discussed the importance of documenting your code. I would only hope at this point that you now see the value of proper, clear, and concise documentation. Sample documented code was provided in Listing 1, and tags you may use were provided in Figure 1. Putting this all together allows for generating documentation via thirty-party tools such as NDoc, as well as enabling the IntelliSense feature to work on your code.

The goal of this article was not to teach you how to document your C# or VB.NET code, but rather to convince you to document your code. Good luck, and keep that documentation up-to-date!



User Comments

No comments posted yet.






Community Advice: ASP | SQL | XML | Regular Expressions | Windows


©Copyright 1998-2019 ASPAlliance.com  |  Page Processed at 2019-04-19 10:35:19 AM  AspAlliance Recent Articles RSS Feed
About ASPAlliance | Newsgroups | Advertise | Authors | Email Lists | Feedback | Link To Us | Privacy | Search