XML Comments & Documentation
I would say there is nothing more important than good documentation with your code. Even the crappiest code can be maintained a billion times easier if it was well-documented. Documentation is a programmer's bible; it guides the programmer through the wilderness that is your code. Yes, even well-written code is still a wilderness without documentation. I don't care if you think you're going to be the only person that ever works on the project. Documentation isn't just for new programmers working on the project either. What happens when you come back a year later and wonder what you were thinking? Well, if you left a comment in the code then you would know what you were thinking!
What does this code do?
public static DataSet UpdateSurveysGrid(DateTime StartDate, DateTime EndDate, Int32 id)
{
List<StoredProcedureParameter> p = new List<StoredProcedureParameter>();
p.Add(new StoredProcedureParameter("StartDate", StartDate));
p.Add(new StoredProcedureParameter("EndDate", EndDate.AddDays(1)));
p.Add(new StoredProcedureParameter("ID", id));
SqlCommand cmd = DBUtil.createCommand("tlbx_AssignmentAdmin_UpdateableSurveySummary", p);
SqlDataAdapter da = new SqlDataAdapter(cmd);
DataSet ds = new DataSet();
da.Fill(ds);
return ds;
}
Well, it updates the surveys grid, duh! How is anyone supposed to understand what this method does? The method name can only tell us so much. It's a public static method which means I can call it from all over my application. But what is it? Does it perform a function I might need? What does it mean to "update surveys grid"? The only way to tell is to walk through the code line by line. Even then, the variable names like p, cmd, da, and ds tell us absolutely nothing. Sure, a seasoned .NET programmer could easily see a stored procedure being built with parameters and then populating a data set, but even he wouldn't know what the heck the data coming back meant without further investigation.
How much easier is this?
/// <summary>
/// Retrieve an up to date result set for all surveys in the system.
/// </summary>
/// <param name="StartDate">The earliest date to pull surveys from.</param>
/// <param name="EndDate">The latest date to pull surveys from.</param>
/// <param name="id">The category ID to look for surveys in.</param>
/// <returns>A set of survey entries matching the search criteria.</returns>
public static DataSet UpdateSurveysGrid(DateTime StartDate, DateTime EndDate, Int32 id)
{
List<StoredProcedureParameter> p = new List<StoredProcedureParameter>();
p.Add(new StoredProcedureParameter("StartDate", StartDate));
p.Add(new StoredProcedureParameter("EndDate", EndDate.AddDays(1)));
p.Add(new StoredProcedureParameter("ID", id));
SqlCommand cmd = DBUtil.createCommand("tlbx_AssignmentAdmin_UpdateableSurveySummary", p);
SqlDataAdapter da = new SqlDataAdapter(cmd);
DataSet ds = new DataSet();
da.Fill(ds);
return ds;
}
Isn't that SOOO much better? Sure, the code needs refactored and even the method needs to be renamed, but that comment makes things so much easier to understand. Pay attention to the XML tags in the comment; these are what make this an XML Comment.
XML Comments
The difference between a plain old code comment and an XML Comment is the presence of XML tags. Also note that an XML comment starts with three forward slashes. The first two slashes signify a comment and tell the compiler to ignore it. The third slash tells the parser that this is an XML comment and should be handled appropriately. This makes some basic intellisense possible in your comments.
XML comments have a common set of XML tags. In Visual Studio when you put your cursor above a method and type the three slashes it auto-generates an XML comment template. This template contains the most commonly used tags. Visual Studio is also smart enough to include <param> tags for each parameter that your method takes as an argument. This enables you to easily document not just the method, but also the parameters it takes.
The best possible practice when you are coding is to XML comment EVERYTHING. Document everything as much as possible. Namespaces, classes, and all members of classes (private or public). Trust me, this will make your life easier in the long run.
XML Comment Warnings
It is possible to set up Visual Studio to alert you when you forget to document a public method or property. To enable this, follow these steps:
- Right-click your project node in solution explorer and go to "Properties".
- Navigate to the "Build" tab.
- In the "Output" section check the box labeled "XML documentation file".
Do a build on your project and you will notice that any public classes, methods, or properties that have not been commented will be highlighted with little yellow squiggly lines. They will show up as warnings in your Error List window. Checking that box also tells Visual Studio to build an XML documentation file when you build your project. This is important because if you are going to reference a documented class library in another project and you want intellisense then you will have to ensure that the assembly's accompanying XML file is in the same directory as the assembly itself.
Building MSDN-Style Documentation
XML commenting everything is often plenty for small development teams, but sometimes you need something more robust. How many times has Microsoft's MSDN Library helped you understand something going on in the .NET Framework? Fortunately there is an easy way to build this kind of documentation for your project. If you've done a good job commenting your code then Microsoft Sandcastle will eliminate a lot of the work involved with building MSDN-style documentation. For instructions on how to install and set up Sandcastle, see this post.
I've even posted a way to integrate Sandcastle into your project's build process so that you don't have to do anything to generate the documentation for your project. Ironically, there is very little documentation out there about Sandcastle which is why I put the tutorial together. Please post comments if you have any issues; I'm always happy to answer questions.