One of the best guidelines for commenting in code is the same guideline to follow in life. This is sometimes called the Goldilocks Principle, also known as the Three Bears Principle, named after the children's fairy tale, Goldilocks and the Three Bears. The essence of this guideline is not too much; not too little; just right. However, just right is subjective, depends on several factors, and will be different for each situation. Your own judgment and experience must be your guide to your Goldilock's moment.
These are essential guidelines to follow when commenting your code:
- Assume the reader already knows the language: You are not teaching your reader how to code. Do not explain the obvious features of the language. You are explaining the non-obvious aspects of your code.
- Write in full sentences with proper capitalization and punctuation: Comments are not code. They are the words you are writing to yourself or to other readers of your code. Your comments will be much less cryptic and more easily understood if you follow this guideline.
- Comment on unusual uses of the language: Every language has oddities and idiosyncrasies that may not be used often or may be used in unexpected ways. These should be clarified and highlighted.
- Try to comment in a way that is resilient to code changes: Very often, as code changes, comments are not necessarily updated to match. One way to mitigate this is to put comments in globs at the beginning of functions or to precede blocks of code rather than them being interspersed within code blocks so that if those change, the comments are still valid. You will see examples of this throughout this book.
- Comment at a high level: Describe the intent of the code and the way it attempts to solve a problem. This guideline goes hand in hand with the first guideline we mentioned. The higher the level the comments are describing, the less likely they will need to be changed as the code changes.
- Convey your intent: With your comments, strive to convey the intent of the code you are writing, why the code is needed, and what the code is trying to accomplish. What the code is actually doing should come from the code itself.
I am often surprised when I revisit code I wrote 6 months ago. Too often I find that I am scratching my head asking, why did I do this? or, what was I thinking here? (both cases of too little commenting). I also find that when I change code, I have to delete many comments that are no longer necessary (a case of too muchcommenting). I rarely find that I have commented too much when I have focused on the intent of the code (what was I trying to do here).
At one point in my career, I came across a programmer whose comments were completely divorced from the code that was there. I concluded that this programmer initially intended their algorithm to work one way, but then modified the code so significantly that the comments no longer matched the actual code at all. When I saw that programmer's name in subsequent code, after careful inspection, I more often than not simply deleted the code comments because I found them to be irrelevant. Please do not do this unless you are absolutely certain you understand the code and that the comments do not match the code.
Learning how to effectively comment on code is a lifelong challenge. I do not suppose you will learn this quickly. You will learn this after years of examining your own code and making your code clearer to yourself, let alone making your code clearer to others. As we work through various C example programs, I intend to demonstrate a variety of useful and resilient commenting techniques.