www.greg-wright.co.uk

I've always thought that the best programmers have the worst memories. The reason is simple. If you have a bad memory you have to write your code in a way that you will understand it in the future. If you have a good memory you can do what you like, give variables stupid names, make the code as unreadable as you like - you can rely on your memory to help you out when you revisit the code.

There is something of an art to writing and commenting code, because its a team game. Not only does your code have to work but it is essential that anyone who reads it can understand it, without it taking them longer to understand it than it took you to write it in the first place. If you write code that nobody else can understand then there is really no point in writing the code. All that can be done is to wrap some unit tests round your code and refactor it to literacy.

Unit tests are a good way of "documenting" code. At least they give usage examples which can help enormously.

So what should your approach be when writing comments? The essential thing is to realise that the code will have to be understood by a domain non-expert. You need to be very clear about what is going on and why it is happening the way it is. Nowhere is this more important than in documenting complex SQL joins. Be particularly aware where you are using side-effects - unusual properties of functions to do something non-obvious, for example the MySQL ABS() function can take varchar arguments and will discard things that are not numbers, the PHP array_merge() function can take a single array as its parameter and will reorder it (See http://www.php.net/array_merge).

In MySQL lines starting with -- are treated as comments - this can be very useful. But whatever you do remember that whoever reads your code will have much less understanding of it than you do. Behave accordingly!