Skip to content

Comments

Express your intent in code do not write more comments. If you are write comments that means that you are fail to write clean code.

Comments Do Not Make Up for Bad Code

Explain Yourself in Code

Good Comments:

Some comments are necessary or beneficial.

write legal comments like copyright and authorship statements are are necessary and reasonable things to put into a comment at the start of each source file.

Informative Comments:

It is sometimes useful to provide basic information with a comment.

Explanation of Intent:

Sometimes a comment goes beyond just useful information about the implementation and provides the intent behind a decision.

You might not agree with the programmer’s solution to the problem, but at least you know what he was trying to do.

Clarification

Sometimes it is just helpful to translate the meaning of some obscure argument or return value into something that’s readable.

Warning of Consequences

Sometimes it is useful to warn other programmers about certain consequences.

TODO Comments : Write TODO Comments.

Amplification :

A comment may be used to amplify the importance of something that may otherwise seem inconsequential.

Javadocs in Public APIs:

If you are writing a public API, then you should certainly write good javadocs for it.

Bad Comments

Don't write bad comments as follows:

Do not write Mumbling Comments. Take time and write good comments of good function name.

Redundant Comments

a simple function with a header comment that is completely redundant. The comment probably takes longer to read than the code itself. So do not write like this.

Misleading Comments

comments tells something and intent of the code tells something so do not write like this.

Mandated Comments

It is just plain silly to have a rule that says that every function must have a javadoc, or every variable must have a comment.

So do not follow this rule.

Journal Comments

Sometimes people add a comment to the start of a module every time they edit it. Do not write journals or log.

Do not Write unnecessary comments like

Don’t Use a Comment When You Can Use a Function or a Variable

Do not write Position Markers.

Do not write Closing Brace Comments .

No need to write Attributions and Bylines.because every thing should take care by source code control system.

Do not write Commented-Out Code.

HTML Comments :Do not write html comments.

Non local Information :

If you must write a comment, then make sure it describes the code it appears near.

Too Much Information:

Don’t put interesting historical discussions or irrelevant descriptions of details into your comments.

Short functions don’t need much description. A well-chosen name for a small function that does one thing is usually better than a comment header. So dont write Function Headers comments.

Don’t write In obvious Connection.