Maybe we need //Comment comment

Do we need comment in our programs? Depends, if we can write a program which can clearly tell s the reader what the program does, then we had better to avoid unnecessary comments. However, if the program we develop is complex enough and it involves some uncommon logic which needs more explanation, then we have to add comment and make sure the comment we add can correctly tell the readers what we do.

The worst scenarios is not you forget or you don't want to add comment, it's that you add comment but the comment you add is wrong or may diverge the readers to think something else. We don't want to add a comment later like this : //comment comment. Right?

Add comment to the program you are writing is not an easy task, it's not just you add // or /**/ and then write a novel or story inside. Sure, you can do that, but someday when some person reads your code behind you back, he may think "what a dude". So don't give him a chance. Then you should read below advice probably.

Do you really need to write a comment?

Before trying to add any comment, ask yourself this question. For some simple programs and if the logic is quite straight forward, then probably you no need to provide comments for it. For example,

//This method sets the speed
public void setSpeed(double speed){
    this.speed=speed;
}

Hey, man. Really? I know what this method does. Don't treat me as an idiot.

But sometimes, you have to add comments. When you write a method which is to calculate the score of some search keyword in a search engine system. It's necessary now for you to write the comment to explain the meanings of different parameters and how the algorithm works. This is not what everybody can easily understand.

private int calculateScore(int titleCount,int descriptionCount){
    //The keyword occurances in title and description is treated differently
    return (titleCount*TITLE_FACTOR)+(descriptionCount*DESCRIPTION_FACTOR);
}

How much comment to add?

If you write too less comment, you may fail to convey the message to the reader; in contrast if you write too much comment, then readers may easily get lost in the comment and cannot read the codes clearly.

Usually we should try to think about ore or two sentences to describe what we are doing. If this program is too complex, for example, if you are implementing a cryptographic algorithm, then the comment may not be enough, you may need to consider to write documentation to document the logic and then put a link as the comment in the program.

What to do after writing the comment?

Once you complete writing the comment, you need to first read the comment yourself and see whether you can understand it or not. Sometimes, we cannot even understand what we write. Trust me, we always do. After that, it's time for your peers to read them. But here I am not advising that you send the comment to them to read directly, instead this step should happen when your peers review your codes, they should not read your codes only, they must read your comments as well. A responsible code reviewer will always remember to do this.

Also, every time when there is code change, may be when you are fixing a bug, you should consider about your comment as well. Many people may forget to update their comment when they update their code. This often causes lots of confusions. We need to develop a habit to update our comment if necessary.

One last point. Write comment, write responsible comment.