Accuracy in Commentsby in Representative Line on 2016-08-24
Comments are rough. I always take the stance that code should always be clear enough to explain what it does, but you’ll may need a comment to explain why it does that. I recently attended a talk by Sean Griffin (maintainer of Rails) who argued that commit messages should accomplish that goal, since they can contain far more content than a code comment, and while code comments and code can drift apart and cease to be accurate, commit messages are always linked to the point-in-time when they were made. Donald Knuth, on the other hand, might argue that code should annotate comments instead of the opposite.
Regardless of the method we use, I think most of us would agree that code needs some documentation in the same way it needs tests: it should exist, but we don’t want to have to create it.