Good comments convey important information to the human reader of the code that the code cannot clearly convey by itself. Comments should add value, making the code easier to understand, and therefore more maintainable. Remember that 80% of the cost of a software project is incurred during the maintenance phase.
“Programming is the art of telling another human being what one wants the computer to do.”
– Donald Knuth, author of The Art of Computer Programming
When I teach software development, I try to instill the mindset that the code you write today will have to be maintained by someone tomorrow, next week, next year, or even decades from now. (Some of the code I have written is still in production use after 25+ years.) Think of the human readers (maintainers) of your code as your customers, and you want to make sure your customers are happy.
Here are some key folks who might read your code:
- You, sometime in the future. (Yes, you are your own customer.)
- Your colleagues, tasked with reviewing and/or maintaining your code.
- Your boss; the person who signs your checks and reviews your performance.
- Potential employers. (Do you really want them to struggle to understand your code? If they do struggle with reading your code, do you really think they’ll hire you to write code for them?)
- Developers you have never met, who are maintaining your code and with whom you might have to work someday (if your code is open source, for example).
I often get questions like:
- Exactly how many comments do I need?
- Do I really have to comment this part of the code? I understand it, so why bother?
- What should the exact code-to-comment ratio be?
My answer is always the same.
There is no cut and dried number of comments or ratio of comments to non-comments in code.
Picture yourself five years from now, picking up the code to make an important change to it, after not seeing it or thinking about it at all during those intervening years. The change might be needed anywhere in the code. What comments do you need in the code today, to make life easier for that future you? Should you comment this section? If there’s any chance you won’t understand this section in five years, then yes. If the answer is no, then substitute the future you with a potential future employer, and ask the same questions again. If the result of this exercise is that you don’t need to comment this part of the code, as long as you’re being completely honest with yourself, then move on.
Over time, after having to deal with your own code and other people’s code, you’ll get a sense of what needs to be commented. But until then, use this exercise to help you make that decision.
I often see both programming students and working software engineers scramble to add comments to their code at the last minute, after all the code has already been written. While this is [usually] better than not commenting at all, it’s much less efficient than commenting as you go along. If you leave all commenting to the end, you run the risk of wasting lots of mental energy and time, trying to re-figure-out what a section of code is doing. You find yourself repeatedly asking yourself “what was I thinking here?” It’s much better to comment each section at the time you’re writing the code, when you already know exactly what you’re thinking (hopefully).
That said, your comments should not just restate the obvious. You should assume that the reader of your code knows the basics of the language. For example, if I have a line of C code that increments the value of a variable, then the comment on this line of code:
count++; // increment the count variable by 1
does not add any value, if the reader of your code knows C. (It’s valuable only if your reader doesn’t know C, and you’re trying to teach them the language. But in production code, where your reader is assumed to already know the programming language, it just turns into noise that slows down the reader.)
In some development environments and organizations, comments are sometimes used to help document changes, ownership of modules, interactions between modules, etc. Local coding standards will typically address the details of these commenting requirements.