In this article I'm going to write about why code and comments go out of sync and what can be done to ensure the better code comment quality during software implementation phase of the software development life cycle.
What leads to poor code comments?
1. In a typical product development company, the software is written once and is read/modified for maintenance after releasing the product to the market. The maintenance activities could be either bug fixes or new product feature implementation. The focus will be to fix those and release without planning to go back to the original design or forgetting to see if the comment written is still valid after modifying the code. 85% of the time, the developer forgets to correct the code comment after modifying the code. This may happen because the time allocated for fixing the issue is not sufficient to consider the design and re-look into the comments.
2. I heard from one of my fellow worker saying that "the Software complexity is directly proportional to the number of developers who developed the software!". And yes in-fact this is very much true. I've seen cases where there is no common understanding between the developers. Each developer is on different page and obviously they can't create a better software. The mentality of the developer that the code is already legacy and no one bothered to write comments and why should I correct somebody's comments?
3. Comments are not 'executed' by the computers. So why write comments if the goal is to complete the given coding task? Well, it would have been so nice if compilers themselves write code comments on behalf of developers! May be this is feature enhancement for compilers!!
How can we maintain better code comments?
1. Impose the rules. Add in the code review checklist that the code comments are 'well' written and importantly ensure that code reviews are carried out without fail. This is true for code being written from the scratch or code being modified for maintenance activities.
2. Have the habit of writing comments first before even writing the code. Its usual tendency of the developer to forget writing comments after writing the code.
3. Encourage developers not to write the obvious comments such as 'Loop through the array' and code a loop next. I still do not understand why some one writes so obvious comments that are absolutely not required. Such comments can easily be understood by looking at the code.
4. Make it a mandatory habit to write 'Why?' part of the comment. This part is most commonly missed in the code comments. Take an example: int nValue= file1.length() + file3.length(). In this example, why not file2.length()? If developer does not write this information then nothing can help understanding this code neither the design nor the requirements that are high level.
The benefits of writing quality code comments are very obvious.
1. The developer reading the code can go home early. (no late nights).
2. You can reduce the potential software bugs that might have been caused due to code changes without understanding the completely why the code was written.
3. Make software developers' life easy and enjoyable at work.
.... I can keep adding several things here.
There are no hard rules here. If your software code does not have better quality code comments, then an activity of just improving the code comment quality can be taken up. Believe me that this practice plays a great deal if the same code is being modified for feature. Better code comments are speed up the code refactoring activities which is performed to build a new software product but reusing the existing code.
Have a look at Code Smells & Coding Standards.
This article is dedicated to all software developers in the world. If feel like sharing the frustration of understanding the code with no comments, leave me a comment.