Increase productivity with XML documentation

Intro

This post was originally a guest blog which you can find: here. Let’s talk about commenting code for a second. I was triggered by this rant http://blog.codefx.org/techniques/documentation/comment-your-fucking-code/ to examine how we actually do this on our team. And as I reviewed our codebases I quickly discovered that almost each and every one of us has a totally different style of commenting. I suggested during a Sprint Retrospective to the team to not only comment our code in the same way, but also in the same manner. In an Agile Scrum environment where seniors leave the team and juniors enter the team we all could agree that this was going to help our code become more readable. To help us getting started on this I introduced the XML Documentation Comments: https://msdn.microsoft.com/en-us/library/b2s063f7.aspx. A style of commenting code I am in to. I’ll first briefly explain what it is and then I’ll explain why I prefer XML documentation over inline comments.

What is XML documentation?

Adding XML documentation is like adding annotations above classes and methods. Except they are not metadata and not included in the compiled assembly (and therefore not accessible through reflection). You can write XML documentation by typing triple slashes directly above the line with the class or method declaration. The Visual Studio IDE will add the correct and commonly used tags. So above a class it looks like:
2015-10-12 16_15_41-XMLTagAboveClass
Figure 1: XML documentation above class

Side note: I am showing wrong comments (as in not revealing intent) on purpose. We’ll get back to that later.

And above a method as follows:
2015-10-12 16_15_41-XMLTagAboveMethod
Figure 2: XML documentation above method

Side note: Notice how the tag ‘param’ is added automatically with the attribute name and the correct parameter name. This is monitored by the IDE and will produce a warning if it’s not correct, so very maintainable.

Above a method with a return type:
2015-10-16 11_18_39-XMLTagAboveMethodWithReturnType
Figure 3: XML documentation above method with return type

Side note: Please note the escape characters around ‘IAgenda’.

The above examples are automatically generated and therefor commonly the most used. If you want to play around with other tags which are recommended for use you can follow this link: https://msdn.microsoft.com/en-us/library/5ast78ax.aspx

Why XML Documentation over inline comments?

So why do I prefer XML documentation over inline comments? Well, there are several reasons:

  • Forces you to think about your comments
  • Maintainable
  • Provides IntelliSense
  • Automatically builds API documentation

I’ll explain them in order:

Forces you to think about your comments

As I’ve said in the side note beneath figure 1 I have intentionally made some horrible comments. Have you ever come across something like:

//Gets a new Foo
public static IFoo GetNewFoo(ICustomer customer){
//New up a Foo
IFoo foo = new Foo();
//If IsPrefered = true then add collection of Bars
if(customer.IsPrefered){
foo.Bars = GetBars();
}
//Return new Foo
return new Foo();
}

What do these comments say? Absolutely nothing more than the code that is written. What should comments do? They should reveal the business intent behind code. They should tell the new guy that has to clean up your mess why the code was written the way it was back then. Let’s try this with more business intent in the mix:

/// <summary>
/// Gets a new Foo for the customer. If the customer is a preferred customer they are ///entitled to a collection of Bars.
/// </summary>
/// <returns>A new instance which adheres to the IFoo interface, which contains a ///collection of Bars depending on whether or not the customer has the preferred status.</returns>
public static IFoo GetNewFoo(ICustomer customer){
IFoo foo = new Foo();
if(customer.IsPreffered){
foo.Bars = GetBars();
}
return new Foo();
}

This example is terribly contrived, but I hope I can make clear what I mean with comments that portray business intent. And I’ve experienced that thinking about good XML Documentation forces you to think more about the comments you write down.

Maintainable

XML Documentation is checked to some degree by the Visual Studio IDE, generating warnings where needed. Inline comments are not checked at all, and how could they be checked? There’s no structure.

Provides IntelliSense

How nice is it to tap the period key, focus on the properties/methods and see a clear and concise explanation? Fantastic right? Imagine having a college seeing the IntelliSense you provided and understand what it does. Awesome right? So to give a concrete example, the IntelliSense for the method in figure 3 would be:
2015-10-16 15_18_48-XMLDoc_IntelliSense

Automatically builds API documentation

You’ve read that correctly. There’s a free open source tool out there which is called Sandcastle (https://github.com/EWSoftware/SHFB) which generates your API documentation based on these XML Documentations. Hook Sandcastle into your Build Definition on TFS and have it generate API documentation as part of your Continuous Integration pipeline!

Conclusion

I hope after reading my blogpost I’ve made you enthusiastic about XML Documentation as well. There are some nice benefits to be had, so drop this in your team the next Sprint Retrospective and see how it will land.

Advertisements

About Danny

Bachelor in Commercial ICT MCTS Winforms .NET 2.0 MCTS ASP.NET 3.5 PSM I
This entry was posted in .NET programming, Visual Studio and tagged , . Bookmark the permalink.

One Response to Increase productivity with XML documentation

  1. Pingback: Tracking code comments with Task List | Danny van der Kraan's Blog

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s