I write a lot of comments in my code: these days it’s second nature. Every declaration I write has a comment describing what it’s for and maybe some remarks describing things I think are the associated gotchas. Inside method definitions, I maintain a running commentary describing what the method is supposed to be doing and why. I feel that comments are the best place for code documentation for one simple reason: the source file is the one thing that you can guarantee that a future developer will read.

This code style is something that has evolved over many years. When I was starting out in development I took a more conventional attitude, that if the code was readable (sensible names, well structured) then it was also automatically understandable. Time changed this attitude. At first, I grew used to looking at the code of other developers and wondering what they could possibly have been thinking while they wrote it and wishing I could throw the whole thing away. Later I found myself wondering the same thing about code that I had written long ago. If I made changes, they would fail in unpredictable ways. The variable names, they did nothing.

Occasionally the problem turned out to be genuinely bad or lazy code, of course. Mostly, though, the problem was one of understanding. Code written in the languages we have available today explains in great detail the steps taken by a program to complete a particular operation. The name of a method or class will usually explain what the operation is. It gets fuzzier as you ‘draw back’ from the individual operations and try to get a higher level overview.

The problem is that developers can usually fill in the gaps in their own code: they can remember writing it and their own reasoning. What seems obvious now might not be obvious to the next developer. At best, this makes their life harder: they need to spend longer looking at the code and its documentation before changes can be made successfully. More often, these ‘obvious’ things will result in new bugs being introduced during maintenance: at worst, these bugs won’t be discovered before the code is in production. It’s better to document something that seems self-explanatory now rather than wait until later when nobody remembers why it was supposed to be self-explanatory in the first place.

So, I set out to document as much as possible, forcing myself to try to write something interesting even about things that seemed they would be obvious. It wasn’t particularly easy at first: the idea was to write comments first and code later but I always felt more productive writing code so I’d have to go back and write the comments later. As I was doing this I found something interesting: sometimes by trying to describe what I was doing I would discover what was wrong with it and I’d be able to fix it much earlier.

I think this idea also appears to be at the heart of the idea of pair programming: if you can’t comfortably explain what you are doing, you are probably doing it wrong. I found that by writing about what I was doing before I did it I would spot logic errors and parts that were not entirely thought through much more quickly: by refining my comments I was finding ways to refine the code. This improved my productivity: the code was easier to read, more structured and I avoided introducing bugs – spending time on the comments meant I wrote less code in a day, but I also spent less time fixing it or working around problems I had introduced.

This is an agile approach to development: documenting design in the code with a ‘just-in-time’ approach. It works well because it is a focussed way of solving a problem – designing and implementing the solution in a single pass. It’s also effective because it makes it easier to keep the documentation in sync; if the documentation is kept in the same place as the thing that it is describing then it’s much easier and more natural to keep it up to date as changes are made.

I think there is a tendency for new developers to eschew comments for reasons that are perhaps ill-founded and which become ingrained. Commenting frequently not only ensures that code remains readable once the original development cycle is distant memory but also provides a time-saving sanity check that can prevent poor code from being written in the first place.