Don’t comment bad code — rewrite it

This is a popular saying by Brian W. Kernighan and P. J. Plaugher. Comments are no way to hide a bad piece of code. If our programming languages are expressive enough which todays OOPS languages are and we have the talent to clearly express ourself in those languages, then we don’t need comments.Because nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation. The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong.

Comments do not make up for bad code :

When we write a module and we know it is confusing and disorganized. So we say to ourselves “I’d better comment that”. No better clean that code

Explain yourself in code :

It takes only a few seconds of thought to explain most of your intent in code. In many cases its simply a matter of creating a function that says the same thing as the comment that you want to write.

By all this does not mean all comments are bad or commenting code is a bad habit. Lets look at some good and bad comments scenarios:

Good Comments

Legal comments : copywrite and authorship statements 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.

Clarification: Sometimes it is just helpful to translate the meaning of some obscure argument or return value into something that’s readable. eg. when its part of a standard library or in code that you can not alter, then a helpful clarifying comment can be useful.

TODO Comments: It is sometimes reasonable to leave “To do” notes in the form of //TODO comments. It might be a reminder to delete a deprecated feature or a reminder to make a change that is dependent on a planned event.

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. But keep in mind, Javadocs can be just as misleading, nonlocal and dishonest as any other kind of comments.

Bad Comments

Mumbling: Plopping in a comment just because you feel you should or because the process requires it, is a hack. If you decide to write a comment, then spend the time necessary to make sure it is the best comment you can write.

Redundant comments: Sometimes the comment is not more informative than the code. It does not justify the code or provide intent or rationale. It is not easier to read than the code.

Misleading comments: Sometimes with all the best intentions, a programmer makes a statement in his comments that isn’t precise enough to be accurate.

Mandated comments: It is just plain silly to have a rule that every function must have a javadoc, or every variable must have a comment. Comments like this just clutter up the code and lend to general confusion and disorganization.

Journal comments: Sometimes people add a comment to the start of a module every time they edit it. These comments accumulate as a kind of journal or log, of every change that has been made. These are not needed as we have very good source code control systems that do it for us.

Noise Comments: Sometimes we see comments that are nothing but noise. They restate the obvious and provide no new information.

Position markers: Sometimes programmers like to mark a particular position in a source file like a banner with some slashes or special characters. If you overuse banners, they’ll fall into the background noise and be ignored.

Closing brace comments: Sometimes programmers will put special comments on closing braces. Although this might make sense for long functions with deeply nested structures, it serves only to clutter the kind of small and encapsulated functions that we prefer.

Attributions and Bylines: Programmers tend to add comments giving information on who made this code change and change date. There is no need to pollute the code with little bylines. The source code control system is a better place for this kind of information.

So we if we keep these good comments and bad comments scenarios in mind, then hopefully our comments can add more meaning to our code.

Happy Commenting !!!

Mobile Application Expert

Mobile Application Expert