Comments

Comments are one of those things I tend to forget about until someone brings it up. I have heard many exaggerated claims about comments dramatically improving a project or how they are essential for success on large projects. I am not sure how big a project needs to be to be considered 'large'. 500k LOC? 1M LOC? That is a conservative estimate for the size of some projects I have worked on and they seemed pretty big. So based on my experiences, are comments really that useful? And what makes a good comment anyway? Should I comment every function? I thought it was about time I had a little rant. It has been a while ;)


Firstly, comments are documentation. Writing any kind of documentation you need to know who your audience is. Writing a user manual is different from writing a business pitch or writing a programmers reference. Fortunately in the case of comments your audience is easy, it is other programmers ... or more likely than not it will be you looking back over some piece of code that you wrote several months ago and can not for the life of you remember what the heck you were doing back then. So I take the view that when I write comments I am writing them for myself. And as I am probably the best judge of what I would like to see then in theory comments should be easy. The problem is, no one likes writing documentation.

There are obviously bad comments, for example ..

i++; // increments i

GetSomeValue(); // gets some value

sprintf( str, "%i", x ); // format the string 'str' with a number

I know what the code does and if it is a library call that I am not sure about I can always look it up. Professional code is not the place for a coding tutorial. Equally, overly verbose comments are bad. Generally I like my documentation to be short and to the point and that is equally true in comments. Several pages worth of comment about a function, how it is implemented and how it is meant to be used quite frankly is not going to be read.

Self Documenting Code

A professional programmer can read code. It is kind of essential really for the job. If I want to know what a function does, or how it does something then I can take look. Comments may not be updated when the code changes anyway so the best place to find out what is going on is with the code itself. With a clear style, sensible variable and function names the code is self documenting, there is no need for comments to explain all the ins and outs of a particular function.

Why, not what or how

The code tells me what is going on, and how something is implemented. What it can not tell me is why something is happening. Comments should add value to the code, tell me something the code can not. Therefore a short description of a class or set of independent classes from a design perspective can be useful. Also, any caveats which come with the code, like a work around for a bug should be commented to stop anyone from accidentally removing them. Optimisations in the code can often look a little odd, and therefore a comment is useful to let you know why something has been done a particular way.

However, there are times when I do like to put comments in telling me "what" or "how". Some functions are large and have several steps to them. Often I find a quick comment at the top of each step useful as it makes skipping through the code easier and quicker. It separates the blocks of code into meaningful chunks. For example ...

// initialise stuff

...


// do stuff

...


// clean up

...

Also it occurs to me that some languages might require more comments than others. Particularly assembly like programming languages (such as VU code for the PS2 or pixel shader code for graphic cards). Assembly is not the easiest thing to read so some comments explaining what is going on is much more useful here.

Commenting before writing code?

There is a school of thought that you should write the comments first before you write the code. This is a good technique if you are dealing with a particularly complex algorithm or are just not sure how you want to implement something. It is like sketching a diagram out on a white board or paper. It has a place in your programming arsenal of tricks but the majority of code is not as complex and I find I rarely need to sketch out individual functions in this way.

Finally I want to cover how comments are sometimes used in other ways.

File headers

People like to add a comment header block to the tops of files. Often containing name of the file, author, license etc. Some source control programs (such as SourceSafe) support this and will insert source control information (checkin comments, time of change, who made the change etc). Open source software often has the GNU license at the top. Personally I find this kind of thing annoying as it is just stuff to scroll past to get to the code (in 'popular' files with 100+ changes this can be several pages).

In the case of distributed code (such as open source) then having the license is probably important and it is useful to have the email address and name of the author if you need to contact them. In large companies then again maybe it is useful to know who is changing what. However the information is also accessible from your source control program so in my opinion unnecessary. Of course you could be looking at a project several years later when the source control is not available. However asking someone about the code then is probably not that useful as they might not be able to remember what they did. Maybe it would be better to have some contact information with the project generally rather than in each file.

AutoDoc Comments

Or possibly "meta comments". Specially formatted comments which are picked up by a documentation generation program such as doxygen, autodoc, phpdocumentor and the like. Often look something like ...

/**
* A description of some function
* @param p some parameter
* @return some value or other
*/

If creating documentation for your project is important then this is a good way to do it as it allows programmers to change or add documentation as they change the code. For example, a function library which is going to be used by another team would be a good candidate. However for most applications external documentation is not as useful and the extra hassle of special comments out weighs any benefit they have.

However I was particular impressed with C#'s XML documentation, which looks like ...

/// <summary>
///
/// </summary>
/// <param name=""></param>

The advantage of these meta comments is they integrate directly with Visual Studio. Creating them is easy as Visual Studio does all the hard work for you by automatically working out what comments are needed. Once you have written them they integrate with the intellisense/autocomplete feature which is very useful. Whilst I do not normally write in C# I do find myself using this feature when I do.

Other Comment Uses

I like separators between functions or sections of the file, by which I mean things like ...

////////////////////////////////////////////////////////////////////////////////

If only because they let me skip through large files quickly. I can see immediately when one function ends and another begins. I am not a fan of code outlining (where functions and blocks are collapsed into expandable sections). I am old school, so I like to see all the code in one go ;) Separators make that easier. Maybe if I get the hang of outlining then they will not be as useful.

TODO's are useful comments as well. Sometimes you leave bits of code that need writing or assumptions you need to address later.

// TODO: save the config data to a file


So long as you always use the same word (so TODO say, and not mixed it with FIX or BUG) and keep the comment on the same line then a quick grep of the code can reveal anything you may have missed out.

Some people like to comment changes they have made. Particularly if it is in a file they are not responsible for.


// GW 2005-12-08: fixed a bug in the file handler - null pointer not being checked for


Whether these add any value is debatable. After all, you can always diff a files history from source control to see what changes someone made. I would rather people did not bother with these as it just gets in the way of reading code.

In summary. Having a good programming style with sensible names means you do not need to rely on comments that often. Write comments for yourself that you would find useful, because it will probably be you who needs to maintain the code several months later. Comment any design decisions, or anything unusual which might catch you out later. If you find using comments useful to separate blocks of code then do it. And do not listen to anyone who tells you comments are some kind of idealised magic bullet for saving the world. If my comments are sparse it is not because I am lazy (well possibly), I have my reasons.

Comments

Popular posts from this blog

Game Development in a Post-Agile World

Polyphasic Sleep - Dymaxion Day 1