It is obvious that only the code can tell us exactly what it
does. So, truth can only be found in one place: the code. We should
always spend energy to minimize comments, but they are sometimes
OpenCV coding style guide has a section named
Writing documentation on functions, that is not very
helpful in general. In addition to that there are always general
points about what is good comment and what is bad comment. In this
Article we will talk about those good and bad comment styles.
// Returns an
instance of the Responder being tested.
abstract Responder responderInstance();
Note: In this case the comment could be made redundant by renaming the function: responderBeingTested.
// format matched kk:mm:ss EEE, MMM dd, yyyy
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");
Note: If this code had been moved to a special class that converted the formats of dates and times. Then the comment would likely have been superfluous.
Explanation of Intent
Sometimes a comment goes beyond just useful information about
the implementation and provides the intent behind a
Warning of Consequences
Javadocs in Public APIs
Our only rescue is to examine the code in other parts of the
system to find out what's going on. Any comment that forces you to
look in another module for the meaning of that comment has failed
to communicate to you and is not worth the bits it consumes.
It's certainly not more informative than the code.
It is just plain silly to have a rule that says that every
function must have a javadoc, or every variable must have a
Long ago there was a good reason to create and maintain these
log entries at the start of every module. We didn't have source
code control systems that did it for us.
Don't Use a Comment When You Can Use a Function or a
Consider the following stretch of code:
the module from the global list <mod> depend on
subsystem we are part of?
This could be rephrased without the comment as
ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
The author of the original code may have written the comment
first (unlikely) and then written the code to fulfill the comment.
However, the author should then have refactored the code, as I did,
so that the comment could be removed.
Closing Brace Comments
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. So if you find yourself
wanting to mark your closing braces, try to shorten your functions
Attributions and Bylines
There was a time, back in the sixties, when commenting-out code
might have been useful. But we've had good source code control
systems for a very long time now. Those systems will remember the
code for us. We don't have to comment it out any more. Just delete
the code. We won't lose it. Promise.
The comment is not describing the function, but some other, far
distant part of the system. Of course there is no guarantee that
this comment will be changed when the code containing the default
Too Much Information
In obvious Connection
Short functions don't need much description. A well-chosen name
for a small function that does one thing is usually better than a
Javadocs in Nonpublic Code
Example of a code full of comments
The same code but this time refactored
Clean Code,A Handbook of Agile Software Craftsmanship, Robert C.