It’s not only capturing the ‘What?‘ but just as importantly the ‘Why?‘ you are doing something that matters in code comments.
For the most part, code should be self documenting. Today is a world of open source, collaboration, and maintenance by many developers. You need to write readable, self documenting code, so others might quickly stand on your mighty shoulders.
However, you’ve probably been in this situation many times. The code looks plain wrong. It is easy to follow and understand, there’s no comments needed to explain ‘What’ the code does. But ‘Why’ is it implemented this way? Why not the more obvious, more sensible way?
At this point the only logical conclusion is to assume this is rookie code that didn’t know any better. So you pick it up for refactoring. You have time. It’s bugging you. And, hey, you’re smart.
Hours or even days later it hits you. Testing passes in come cases, or some environments, but not in others. You’ve now lost considerable time diagnosing the reasons. Eventually you find the reason for things not working using your improved implementation, but now you must accept that unsatisfying feeling when you’ve driven for miles in the wrong direction and must spend more time retracing your journey. You return to the original implementation.
So it was done the original way for a reason, and not because of rookie ignorance. The original developer lost as much time trying to do what seemed sensible, and yet, all it would have taken was a one or two line comment to say ‘Why‘.
So remember, when you’ve lost time investigating why you’ve had to settle for the less obvious implementation. Comment the ‘Why’ for the next guy!