Over the years my thoughts on commenting of code has varied quite dramatically. On the one hand, comments can lend clarity to code, provide valuable documentation and even help to break up the structure of code into managable chunks. One the other hand, comments are deodorant for smelly code, monstrous blobs of text no one can bother to read, or just plain wrong. In an ideal world, your code will be gorgeously self-documenting and as readable as a good book.
Since when have programmers worked in an ideal world?
At the moment, my code comments have reached a stage that is, or aims to be, simple and concise. I’m going to outline the concepts based on commenting of functions or methods. Comments can be one of the religious wars of computing, so I’m not expecting everyone to agree with me. It works for me, it may or may not work for you. To some, it might also be blatantly obvious.
The starting point is not the comments themselves, but the method / function declaration. Is the method name self-revealing? Do the arguments make sense? Calling something x() or foo() or doStuff() could mean anything, while is_numeric() or calculateSumOf() expresses more about what the function does. Of course, if is_numeric() actually returns climate data in XML, then you have a serious naming problem. Likewise, an argument name of x or y probably doesn’t reveal much compared to something like username or payment_type. Before you get as far as writing any comments, think carefully about the method name and arguments – and make sure they’re readable out loud!
Now write a brief comment describing the method. We’re not looking for an essay because no one seriously reads a comment of more than a few lines. In one or two lines, what does it do? What do the arguments mean? If you’re using a dynamically-typed language, what are the arguments expected to be? What is returned? Can the method throw any exceptions? Keep it clear and simple because people want to be able to see at a glance the information they need. If your implementation language supports some kind of documentation comment then use it so IDEs, documentation systems and other tools can parse the text.
If you can’t write the description in one or two lines, that could indicate a problem: your method might be doing too much or could be quite complex. I’ve found the hard way that if I’m struggling to describe what a method does, I haven’t thought the problem through sufficiently. Having to write out the details of lots of arguments is another warning sign of smelly code. You might have too many arguments, you might even lack a clear idea of what each argument does.
Keep comments general so people get an overview of what the method does. The code should indicate the implementation details, not the comments. Generalised comments also help if you refactor the function, changing the internals shouldn’t mean an overhaul of the comments just because you went from a linked list to a binary tree. Keeping it general helps keep things in people’s mind. Much as we like to boast of our mental prowess to our peers, the simple fact is that the human brain can’t hold much in the front of the mind. Be gentle to the reader.
Another great advantage of short, general comments is that it encourages keeping comments fresh. Updating a one-liner to reflect some refactoring you’ve made is easy, adjusting a 30 line essay is not. Stale or contradictory comments rapidly become serious problems.
Comments should be part of your coding tool box. As well as the obvious documentation aspect, they’re a great way to figure out how understandable your code is. When you write a comment, take a good look at the code because too many comments are a sign of something wrong. Comments support the code, providing clarity and insight, they should never contradict or state the obvious. Finding the right level of comments in your code is something that comes with practice.