Top Most 10 best practices to follow while writing code comments

Comments are an important part of writing code not only in java but whatever programming or scripting language you use. At the same time this is one of the most abused things also. Both writing no comment and writing too much comment is bad and in this article I am going to share with you guys some 0f the rule and best practices I follow while writing comments. Before that let's first see what is the purpose of having comment in the code? Why do we need comment, isn't writing code is enough. Some of the people I have met always argue that we are getting paid for writing code and not comment :).

Anyway in my opinion we all agree with each other that software spend only 10% time of its life in development and rest of 90% in maintenance. This 90% part of maintaining the code is where comment can help you immensely. Since no single developer stays till whole life of any product of software and its often new people who works of already written code, these are the people who read the code and not aware of why a certain piece of code has been written, here comments help you to understand code quickly and believe me you will get lot of roses from that fellow developer :)

Anyway long story short here are some of the things I try to follow while writing code:

10 tips on writing code comments

1) Focus on readability of code; assume that you don't have comments to explain the code. Give your method, variables and class meaningful name.

2) Don't write what code is doing, this should be left for the code to explain and can be easily done by giving class, variable and method meaningful name. For example:

//calculates square root of given number 

//using Newton-Raphson method

public void abc(int a){

       r = a / 2;

       while ( abs( r - (a/r) ) > t ) {

       r = 0.5 * ( r + (a/r) );

       }

       System.out.println( "r = " + r );

}

Above code is calculating squate root using Newton-Raphson method and instead of writing comment you can just rename your method and variable as follows:

public void squareRoot(int num){

       root = num/ 2;

       while ( abs(root - (num/ root) ) > t ) {

       r = 0.5 * (root + (num/ root));

       }

       System.out.println( " root = " + root );

}

3) Always write why you are writing this piece of code, why you are writing this piece of code because this information is not visible until you write them in comments and this is critical to identify any bug or behavior with chaning business environment.

4) If you are writing core libraries which will be used by different project and with different teams. Follow javadoc comment style and document all assumption and precondition for using your API.

5) Include JIRA Number and description on comment, especially if you are modifying an existing piece of code as part of maintenance. This I found extremely useful while comparing different version of code in CVS or SVN. This gives you clear idea why that particular code has been added and whether issue is beause of that piece of code or not.


6) Always try to finish your comment in as few words as possible, one liner comment is best until its explaining "Why" part and can't be replaced by code itself. No body likes or has enough time to read longer comment.

7) Don't write story in comment as your name, employee id, your department etc because those information can be obtained from cvs commit data in case someone wants to know who has make this change.

8) Always put comment while commiting code in source control repository and especially why you are adding this piece of code if possible include JIRA or QC Number so that any one can refer JIRA for complete details.

9) If you want upcoming developer to follow certain standards or inform about certain things then include them in the beginning of your class as comment. E.g. suppose if you are writing serializable class in java then its good to put a serializable alert stating that any new fields addition in this class must implement serializable interface in java or make it transient etc.


10) Last but not the least give your code to fellow developer to understand as part of code review and ask him how much he understands it.

That’s all from me on code commenting, please share the standard, best practices or your experience with writing comments on code. I believe these are the areas which a junior developer or even we can improve and it’s only possible from learning which each other's experience.
Happy weekend :)

Related post:
How HashMap works in Java?
How Garbage Collection works in Java?
Why String is immutable in Java?
Why wait and notify method must be called in synchronized context?
10 practical tips on Java debugging with eclipse
How Synchronization works in Java?
How Classpath works in Java?