Comments

Always try to explain yourself in code.

If our programming languages were expressive enough, or if we had the talent to subtly wield those languages to express our intent, we would not need comments very much—perhaps not at all.

Inaccurate comments are far worse than no comments at all. They delude and mislead. They set expectations that will never be fulfilled. They lay down old rules that need not, or should not, be followed any longer.

Truth can only be found in one place: the code. Only the code can truly tell you what it does. It is the only source of truly accurate information. Therefore, though comments are sometimes necessary, we will expend significant energy to minimize them.

Explain Yourself in Code

Rather than spend your time writing the comments that explain the mess you’ve made, spend it cleaning that mess.

Good Comments

Sometimes our corporate coding standards force us to write certain comments for legal reasons, for example, copyright and authorship.

Informative Comments

In this case the comment lets us know that the regular expression is intended to match a time and date.

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. In general, it is better to find a way to make that argument or return value clear in its own right; but when its part of the standard library, or in code that you cannot alter, then a helpful clarifying comment can be useful.

Warning of Consequences

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

TODO Comments

TODOs are jobs that the programmer thinks should be done, but for some reason can’t do at the moment. It might be a reminder to delete a deprecated feature or a plea for someone else to look at a problem. It might be a request for someone else to think of a better name or a reminder to make a change that is dependent on a planned event. Whatever else a TODO might be, it is not an excuse to leave bad code in the system.

The TODO comment explains why the function has a degenerate implementation and what that function’s future should be.

Javadocs in Public APIs

There is nothing quite so helpful and satisfying as a well-described public API. The java-docs for the standard Java library are a case in point. It would be difficult, at best, to write Java programs without them.

Avoid redundant comments

A comment is redundant if it describes something that adequately describes itself. Comments should say things that the code cannot say for itself.

Misleading Comments

The method does not return when this.closed becomes true. It returns if this.closed is true; otherwise, it waits for a blind time-out and then throws an exception if this.closed is still not true.

Give up mandated comments

It is just plain silly to have a rule that says that every function and variable must have a comment. Comments like this just clutter up the code.

Remove 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 ever been made. Nowadays, however, we have source code control systems that did it for us. They should be completely removed.

Don't make noise

Noise comments restate the obvious and provide no new information.

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

Avoid position markers

There are rare times when they make sense, but in general they are clutter that should be eliminated.

Avoid closing brace comments

If you find yourself wanting to mark your closing braces, try to shorten your functions instead.

Avoid HTML comments

It makes the comments hard to read in the one place where they should be easy to read—the editor/IDE.

Remove Commented-Out Code

Few practices are as odious as commenting-out code. Don’t do this!

Don't give too much information

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

Function Headers

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.

Javadocs in Nonpublic Code

As useful as Javadocs are for public APIs. Generating Javadoc pages for the classes and functions inside a system is not generally useful, and the extra formality of the Javadoc comments amounts to little more than cruft and distraction.

Don’t offer systemwide information

If you must write a comment, then make sure it describes the code it appears near. Don’t offer systemwide information in the context of a local comment.

The following example, aside from the fact that it is horribly redundant, also offers information about the default port.

Last updated