Personally I try to only comment the "why", as this is what you can't figure out from code. Having a good revision control system allows you to log the "why" w

Personally I try to only comment the "why", as this is what you can't figure out from code. Having a good revision control system allows you to log the "why" why even better. Comments themselves have, especially when you have lots of them, a really high danger of not getting updating and therefor becoming a liability. When you write code you are supposed to write (1) the tests, (2) the documentation and (3) the actual code. Only one of those can make what you want to happen happen, and one of those is annoying if it doesn't get fixed but one of those wont do anything if completely wrong. At least not right away.