Code Snips

Its been a while since I last posted, primarily because of my health, but also because I am working on something that I don’t wish to post on until I have it all together.  However last week at work I was helping a friend with his code, specifically logging and how it should be written for the reader which got me to thinking about code commenting too.  Writing comments is a lot like writing log entries, you need to dump the technical and get with the intentional.  It’s definitely more art than science but there are some basic practical rules of thumb that should help.

Thumb Number 1 – Do not repeat the code, it’s already been said

So let’s start with a classic.

/* c is an integer */
int c = 0;

I just love this, it reminds me so much of grading first year papers at university.  Yes my friend c is an integer, and if you look really closely that’s just what the code says.  So why say it again?  Why not?  The first question is rhetorical the second deserves an answer.  In general do not repeat what is said in the code as if you change it you make a messy maintenance trap for yourself.  If you come back and change the code you need to change the comment.

Thumb Number 2 – Do not state your intentions, they may change

Our next example is little better than the first.

/* c is a counter */
int c = 0;

Surprisingly the comment is a lie. The variable c is not a counter, not yet anyway, it is just an integer. It might be used as an counter later, but that might change and stating intentions like this might be very noble but ultimately it could be very misleading and cause grief. So rule of thumb is if it is obvious then just don’t do it. In fact it is difficult to justify the commenting of variables of built in type. Even commenting complex types or imported types such as the following are somewhat hard to justify.

/* f is a pointer to a file */
FILE *f = null;

Thumb Number 3 – Talk to your audience, they want to know your thoughts

Write your comments so that your reader knows what you were up to when you wrote the code. I recently have the privilege of reading some nice looking C code. Unfortunately it was completely uncommented. So when I looked at a function called trim_field there was nothing to tell me what the code was actually doing. As it turns out it also replaced the unprintable characters in the field with printable characters.

void trim_field(char * f, int l)
{
    int c = l;
    for (c = l; c > 0; c--)
        ...;
}

Naturally I’ve changed just about everything to protect the guilty but the essence is there. All you need to consider is that an unprintable character is ‘\0′. Now read it again with a comment.

void trim_field(char * f, int l)
{
    int c = l;
    /* Replace all of the non-printable characters in the field
       with a space. */
    for (c = l; c > 0; c--)
        ...;
}

Now the first example is completely valid even though it does not operate on the first character of the field. That is because there was no statement of what the code should do. Note that the comment does not break principle number 2 as it is a statement of what the code should do at this point, not a good intentions statement of what something might be used for in the future. So from the comment we see that the code does not conform because the comment says all but the code does everything but the first one. If there had have been a comment like this in the code that I was reviewing I would have saved about half an hour of time. It takes less than 16 of such issues to soak up a day’s work.

Thumb Number 4 – Explain yourself, give the reader some context

Sticking with our little trim_field example for a while, it would also have been very helpful to know what the function was supposed to do without having to work through the code. If you look at the Java coding standards generally adopted because of automated documentation tools, for example Javadoc, you will see a fascination with the fields in and out. Which is not a bad start. However because we human animals tend to like filling out forms we seem often to forget that there is more to life than just forms and hence a lot of Java documentation stops with the enumeration of fields. So lets take this approach with our trim_field example.

/*
 * function: trim_field
 * input: char * f - a pre-populated string of characters to trim
 * input: int l - the number of characters in the string f
 * output: none
 */
void trim_field(char * f, int l)
{
        ...;
}

Lovely. But really unhelpful and it does break thumb number 1. This sort of commenting came about not to help the reader but to help the documenter. In reality its just a form to be submitted to a tool that will produce a library of code interfaces or API. However its a mistake to think that this is all that is necessary. To be fair I’m probably being overly harsh on the Javadoc guys, its not their fault, they actually do allow for a great deal of excellent commenting. But the human creature seems to be a lazy one and so frequently this is all I see when presented with code for review. So lets move on.

/*
 * function: trim_field
 *
 * description: This function takes a pointer string of characters and
 * changes it in place it so that:
 *  1. The string is terminated with a \'0' after the last printable
 *     character if the last printable character is not at the end of
 *     the string.
 *  2. All non-printing characters once the trim has been performed are
 *     changed to a space character.
 *
 * input: char * f - a pre-populated string of characters to trim
 * input: int l - the number of characters in the string f
 * output: none
 */
void trim_field(char * f, int l)
{
        ...;
}

Of course this could be dramatically improved, but that is where the art bit comes in. You see the function has been explained and now if you see the code doing something different you can quite happily question its validity. It also says to the reader that this dangerous little piece of code is going to reach back into the context of whoever set up f and monkey with it’s internals. This is quite a valid thing to do but now at lest your reader is aware of it.

Thumb Number 5 – Don’t drown your code, your audience may not be lifesavers.

Now it seems a little odd but there are those amongst us who swing to the other end of the commenting pendulum and go absolutely berserk. This at first seems good. I’m firmly in the camp that says if you remove all of your code you should be left with a commented architecture. But at the same time if you end up with a lot of words to explain your mind, give it more thought.

The objective of commenting is to enhance your code. Get stuck in, be brief, get out. For example the following snippet from above could easily be grossly over embellished.

/*
 ...
 *  1. The string is terminated with a \'0' after the last printable
 *     character if the last printable character is not at the end of
 *     the string.
 ...
 */

It might be tempting to explain why it was decided to terminate the string with a ‘\0′ instead of lets say returning a new length for the string. This could make it look more like the following.

/*
 ...
 *  1. The string is terminated with a \'0' after the last printable
 *     character if the last printable character is not at the end of
 *     the string.  We could alternatively have simply returned a
 *     new string length but doing so may have created errors for
 *     boundary checking in code elsewhere.
 ...
 */

Which is very nice and descriptive, but this is code and not a novel. Such comments belong in other documents based around requirements perhaps referring to coding standards. If you were to go berserk and include comments like this consistently it would eventually obscure the code during review.

When writing anything, especially in communicating thought, the following quote is worth remembering.

If you can’t write your idea on the back of my calling card, you don’t have a clear idea. ~David Belasco

Thumb Number 6 – Consider your audience’s desires, lest they surprise you

One of the great bug bears of my life as a software engineer/architect has been the misinformed idea that coders write comments primarily for themselves. This is not the case. There is a lovely quote that I like which illustrates this quite well.

The past is a foreign country; they do things differently there. ~Lesley P. Hartley, The Go-Between, 1953

What we all fail to remember is that we are not the same person tomorrow as we are today. Yes the tense is right. Those two people will look at things differently and be approaching the matter for different reasons. Any comment written should be for a stranger, so what do you want them to see? How will they be looking at your code?

A number of different people will be looking at you code, but generally they can be classified as three distinct groups; hunters, renovators and free loaders. You, as a coder, will probably be all three.

• Hunters are looking to kill some thing. Normally a bug. Sometimes they need to simply find out why a feature behaves the way it does. To help this creature comment infrequently but cover the essence as shown in thumb 2.
• Renovators are looking to extend your work. Make sure that maintaining your comments are easy. Be brief, be concise and be consistent.
• Free loaders just want to use your code. Summarise so that they don’t have to look to far into the code itself. Make sure that automated document schemes can pick up the relevant comments that make an API useful.

When you think of your code from these perspectives it will help identify areas of weakness before you submit it for the inevitable code review. Hopefully it will help the quality of your code overall.

In practical terms you should treat each page of code as a written work. Once you have completed the framework (code) and embellished it (commented) review it as a single piece of work from each of the three perspectives to help those who come along after you. You will be helping yourself.

Finally

I guess the real key to commenting well is not the rules, the coding standards, the automatic documentation tools, the IDE automated cross referencing or even grammar and spelling. All of these things are very useful and I recommend all of them, the secret to good commenting is writing for people so they can use what you have written.

In late January I suffered a rather nasty medical event which had me on my back for a few weeks and will probably not have me back to full health for some time.  One of the things that helped me was Chess and programming.  Help meant proving to myself that my mental faculties were completely intact.  My results in Chess were no more rubbish than usual so that proved a little but programming has helped a bit more.

Any way we have been trying different things to encourage our children to learn maths so I wrote a little maths testing tool to help us.  Its plain, not fancy, just asks questions and keeps count of the results.  The idea is that we can get one or other of the urchins to run a few tests when they ask for something.  So we get them to get 200 questions correct and then they can play their game, watch TV or whatever.  It has no rules so you can make them up as you want.

So it’s here, if you want to play.  Real simple.  An example of what you can do with a little HTML, CSS and some simple JQuery.