A while ago, I was searching about comments. Specifically, strategies to comment better. I found the following example:
// // Dear maintainer: // Once you are done trying to 'optimize' this routine, // and have realized what a terrible mistake that was, // please increment the following counter as a warning // to the next guy: // // total_hours_wasted_here = 42 //
LOL.
Who writes comments like that?
Here is another one:
// somedev1 - 6/7/02 Adding temporary tracking of Login screen // somedev2 - 5/22/07 Temporary my a**
And so on.
You will find funny comments when you try to search for how to write effective code comments.
The reason I was searching about writing comments better is that I hate comments. Initially, I believed that everybody loves writing comments in their code. In my research, I found that many developers hated comments. Hence, I am not alone.
Why We hate comments?
We hate comments because comments are boring. I know one time our team was given a task to add comments to an existing project. Each team members have to read the comments written by another teammate and give suggestions.
It was so boring that nobody read comments written by their teammates.You can argue that it’s the laziness of the team. But developers in the team understand the importance of code comments.
So why our team hated this commenting task?
The culprit was the dedicated task of writing comments to an existing code. Writing comments on the fly is easy. Compare writing comments for a completed project vs writing comments as you code.
Writing comments to an existing project is like documentation and developers hate any kind of documentation.
On the other hand, writing comments on the fly is easy and sometimes addiction. For example, one developer even commented the following line of code:
// Saving customer to database aCustomer.Save();
Therefore, we like to write comments when we are writing code.Some people talk when they are writing comments- I know this because I sometimes talk when I code.
Another reason we hate comments is that we have to manage them. For example, you have written comments for some lines of code and the next day you change the code. But you forgot to change the related comments.
Keep doing this for 2 months and one day you will find that there are so many unrelated words written by aliens.
So we have to manage comments in addition to code. Therefore we hate writing comments.
Benefits of comments
We all know comments are good. Our bosses are kept telling us to write comments. So that they can fire us someday and hire someone else to do the job. Comments will make that transition easy!
Because the new hire would read the code — and understands the code magically with the help of comments and they will live happily after.
This reminds me of another funny comment:
//When I wrote this, only God and I understood what I was doing //Now, God only knows
Jokes apart, commenting code is beneficial for the reader of your code. This reader can be you — in distant future.
You can use comments to warn others. While reading code, it looks like that you can follow a straight and obvious approach. So there is a temptation to change the code from complex to simple. This is often wrong.
Another benefit of using comments is: It helps you while refactoring. Refactoring is a process to improve the quality of your code. When you see too many comments around a code listing. It’s good hint for you to refactor that piece of code.
So you wanted to write comments that are helpful. You want to write good comments because you wanted to understand the piece of code that you have written 5 years ago.
Or, you want to give your code to someone else and don’t want that guy to bother you every 10 minutes.
I found the following guidelines helpful. This will helped you write minimum and effective comments for code even if you hate comments.
How I write comments?
The key idea here is to write minimum and effective comments.
I divide comments into two categories. Head comments and inline comments. Head comments that you write before creating a class or creating a function. Head comment define the reason for the creation of that class or function. Head comments can be described as big picture comments.
I use head comments frequently. Because head comments are helpful for getting the overall picture of the code.
I also write head comments to warn the other guy (or yourselves in future). In future, somebody will try to optimize your code because he or she think that there is a simpler way to write your code.
You know that obvious way. You have tested it and you have gone through the pain. You just know that the obvious way does not work. Hence you give the warning to the smarty-pants.
You can also use head comments to explain your reasons. Why you choose that particular strategy and not the other.
Inline comments are those you write to elaborate the code listing. This is the place where you can write spaghetti comments.
What can you do to minimize inline comments? Answer: Write good code.
Quote:
”Dont comment bad code – rewrite it” —Brian W. Kernighan and P. J. Plaugher
It means re-structure your code by assigning a proper and sensible name to code modules: variables, functions, and classes.
How can you assign a sensible to name to a function or variable?
One approach that I used is object oriented analysis and design (OOAD).If you are using an object oriented programming like java or C# you can use object oriented analysis approach to assigning good names to code modules.
Object oriented analysis and design help you to model the real world. This is also called the domain for which you are writing the software. For example, in a banking software, you can have classes like Account, Ledger and etc. Using this concept you can assign names that are close to real world names.
When you assign real names to variables, functions, and classes then it is easier to work with the code. The code will be like reading a standard operating procedure(SOP).
For example, consider the following code
Record rcd = new Record(); rec.Verify(); rec.store();
Vs
Customer aCustomer = new Customer(); aCustomer.VerifyPersonalData(); aCustomer.Save();
Moreover, using OOAD you can work at a higher level of abstraction. Working at a higher level of abstraction makes it easier for a developer to understand the general flow of the code. Consider the following code:
NetworkDevice: IDevice
USBDevice:IDevice
Interface IDevice{
Public byte[] read();
}
In my main code, I have this line
device.Read();
Here, I am working at a higher layer of abstraction and I don’t care about the specifics. In the example above, I don’t know which device will be called ultimately. Hence, I move on to next line of code. If I want to drill down I can go the implementation of the device I am interested in.
Hence, OOAD enables you to write at the higher level of abstraction and this will lower the complexity of reading the code.
The idea of OOAD is that you write code in such a way that comments become redundant. Hence using the real world naming convention and writing code at the higher level of abstraction minimize the number of comments.
These strategies helped me write minimum and effective comments. What strategies have you used to write better comments?