I can't agree with this enough. There are many reasons why code can be obtuse, from first pass un-refactored code, to performance constraints. Comments are tot

I can't agree with this enough. There are many reasons why code can be obtuse, from first pass un-refactored code, to performance constraints. Comments are totally essential and explaining why code was written in a particular way is helpful. However Ari's point I think is even more critical. The code was written to solve some business problem, whatever it looks like it needs to continue to deal with that problem. I particularly like the pointer to a requirement ticketing system (Y! use bugzilla for this). That way you can see all the previous discussion around the business requirement without sullying the codebase. I can't +1 this post enough.