Saturday, October 27, 2012

Importance of Writing Code Comments in Software Development

Every developer knows that 80% of the time, the code is read than written during the software life span. If somebody does not know this fact, its better to know this now. Have you ever stayed late at office understanding the legacy code written by a developer other than you some 10 years back and had tough time understanding it? This has been the challenge in maintaining the software systems over the period of time. The documentation work done for the coding work will almost be out of sync with the current code over the curse of time. So the documentation or the design artifacts do not help in understanding the code logic simply because they were never updated when some body changes the code. I agree that design document helps understand the code at high level, however to completely understand the code logic, its only the person writing the code who needs to write comments for others.

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.


  1. int nValue= file1.length() + file3.length().

    This line *does not* need a comment! nValue needs to have a meaningful name.

    Recommended reading:

    1. Johns, I agree that nValue needs a meaningful name and that must be meaningful enough to explain why are only lengths of file1 and file3 are being summed up and why not file2. If the variable name does not explain this then definitely a line of comment would help!

    2. Were file1 and file3 better-named, then perhaps the next programmer to read this code wouldn't need to wonder why "file2" (or "irrelevant_file") was excluded.

      If the variable names cannot explain the assignment, then it should be extracted into a method with a meaningful name. This also provides the opportunity for unit testing.

      Comments should be seen a failure to express one's self in code.

  2. I am very happy to read your articles it’s very useful for me,
    and I am completely satisfied with your website.
    All comments and articles are very useful and very good.
    Your blog is very attention-grabbing. I am loving all of the in
    turn you are sharing with each one!…
    software development company


  3. It is really a nice and helpful piece of info. I’m glad that you simply shared this helpful info with us. Please keep us
    informed like this. Thank you for sharing.
    mobile application development

  4. Thanks, I like this post it is very good and informative. I am sure that this post will be very helpful and informative to all readers.

  5. Thanks for such social platform which give us variety of idea to explore ourself technically .This exposure give benefits to everyone to fit or to survive in global market which is very essential in the global era.Time Attendance System

  6. Wow nice information in your blog it's a great blog. I got it very important information in your blog that's great ....... :)

    Web Development Company

  7. For companies, the code review is a tool that should not be ignored, it is an extremely useful chance of your developers to learn from each other, in a way that they cannot do during the normal day to day.

  8. Code comments are actually really important, especially for open-source software solutions. These comments are important for the developer community in order to understand why certain code snippets are used and to overall help other developers immediately understand lines of code without the need to read to far above or below.



Related Posts Plugin for WordPress, Blogger...