Comment, because people
“Good code doesn’t need comments, it should be self-documenting and easy to understand.”
This is a quote from one of my former computer science professors in college. I’m referring to it here because, frankly, I completely disagree.
Comments don’t get as much attention as they deserve. They are the key to clear understanding of what code snippets are supposed to do. While code should be written to be easily understood, people approach different problems in different ways. What’s obvious to one person may not be obvious to another, and a lot of problems can be solved if there was a simple one-liner somewhere that explains the need for some conditional or assignment statement.
A lot of people, myself included, have often fallen into the trap of leaving comments as afterthoughts. This results in meaningless words that even the original commentator can have trouble figuring out. The tendency is to think, “I’ll finish figuring out the implementation before writing any comments,” when we should be figuring out the implementation in English before writing any code. Comments serve as a roadmap, both to the developer writing them and to the people reading them.
We’re only human. We forget, we misunderstand, we make mistakes. Comments can serve as our primary weapon against that. They spare our future selves countless hours of tracing and they let our co-workers flip straight to the same page we’re on. We can save everybody time by just writing comments.
Good code needs comments. Good code needs comments because people.