Jason Baker wrote Myths About Code Comments. I like posts like this – they get me thinking about the assumptions I make in my day to day work.
In short, Jason says the following are myths:
- Comments are free
- Comments make code more readable
- You should comment every function, method, class, and module
- Code must always be "self documenting"
In particular, I think the first and second points are intimately related. Anything that goes into a product – documentation, code, comments, tests, etc. – is never free. Anything that goes into a product incurs not only the cost of initially creating but also the ongoing cost to keep up to date. If you avoid the ongoing cost by not keeping all items up to date, the result is that the code and the supplementary material diverge – which leads to the myth that comments make code more readable.