Using XML documentation comments

A while ago I read an excellent book called The Pragmatic Programmer. One of the main themes throughout the book was the DRY principle. DRY stands for Don’t Repeat Yourself. I’ll blog about that another time, as talking about it now would be a violation of the DRY principle later. Anway, the authors of the pragmatic programmer suggest that in order to avoid repetition in different forms where possible code should document itself.

Visual Studio offers a tool to help you do this. You can decorate your code with special comments by typing in three forward slashes. One of those tools is the xml comments feature that helps you comment functions in a useful way.

 /// <summary>
 /// A summary of what this method does.
 /// </summary>
 /// <param name="pFantasticString">The significance of the pName parameter that is passed in.</param>
 /// <returns>Information about what this method returns</returns>
 static bool AwesomeMethod(string pFantasticString)
 {
    return true;
 }

This is really handy for two reasons. The first is because it gives you a helpful structure, and a reminder about what sort of information you might want to put in your comments (However sometimes good naming of variables make the comments a little redundant). The really nice thing about documenting your code in this way is that visual studio can use this to populate intellisense, so people using this method don’t even have to find the definition to read these comments. They just pop up as and when they might be required.

Two examples of intellisense using my comment to deliver information when it might be needed

As I said, good method and function names can sometimes render such comments redundant, but sometimes they are invaluable.

Intellisense being really useful

Take this example using the .net Random class. This comment reassures me that if I ask for a random number and pass in 0 and 5, then there is a chance I will get 0, rather than the lowest value possible being 1.

Additionally, by checking a box in a project’s build menu you can get visual studio to create an xml file of your project. This could be used to create documentation for the internet automatically, using tools such as Sandcastle.

Don’t be a parrot programmer

When students are learning to program they know that they should comment their code, but knowing what code to comment is an art, as is knowing what code not to comment. Sometimes, especially if comments are mentioned in the marking scheme, students will make an extra effort to add comments. Often that results in what I call parrot comments.

Take a look at this code that gets a random integer:

Random randomNumberGenerator = new Random(); // Random Number Generator

int getRandomInteger(int pMinimum, int pMaximum)
{
    return randomNumberGenerator(pMinimum, pMaximum); // returns random integer between pMinimum and pMaximum
}

This is what I call parrot commenting, and I think it’s symptomatic of someone who knows they should comment, but doesn’t know what to comment.

Comments should always add something more to the code; otherwise they aren’t comments, they’re just clutter. This is made worse in the code above, because the comment is worse than clutter. It is actually wrong!

Random randomNumberGenerator = new Random();

int getRandomInteger(int pMinimum, int pMaximum)
{
    // returns random integer greater than or equal to pMinimum but less than pMaximum
    return randomNumberGenerator(pMinimum, pMaximum); 
}

This comment is correct, and it adds something to the code that we didn’t know before – so it passes the clutter test. I think the key to comments is to describe what you are doing and why as you write the code. Otherwise you come back, read the code and describe what you have read. Well any programmer could do that.

Writing code that comments itself

Welcome to the first post for a hypocrites guide to comments!

My first piece of advice in my guide to comments is that you shouldn’t use comments.

That is, if you choose your variable names and method names well, lay out your code well and your code is doing something trivial ( I mean really trivial, not something that seems trivial now but won’t be in three months time when you’re no longer immersed in the project) then your code might not need comments.

To illustrate this consider have a look at this code:

float a(List <int> b)
 {
 int c = 0; float d = 0;
 for (int i = 0; i < b.Count; i++){
 if (b[i] != 0)
 {
 d += b[i];
 ++c;}}
 return d / c;}

Can you work out what that code does? How long did it take you to work it out?

Now look at this code:

float getAverageNonZeroMark(List <int> pListOfMarks)
{
   int numberOfNonZeroMarks = 0;
   float totalSumOfNonZeroMarks = 0;
   for (int i = 0; i < pListOfMarks.Count; i++)
   {
      if (pListOfMarks[i] != 0)
      {
         totalSumOfNonZeroMarks += pListOfMarks[i];
         ++numberOfNonZeroMarks;
      }
   }
   return totalSumOfNonZeroMarks / numberOfNonZeroMarks;
}

Can you work out what that code does?

From the machine’s perspective these two pieces of code are pretty much the same. I expect that the compiler will perform the same optimizations on both pieces of code and two end results may well be identical. From a programmers perspective though, the two pieces of code are far from equal.