Comment Style in OpenCV

Monday September 28, 2015

by Mahmoud FarshbafDoustar at 12:28

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 necessary.

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.

Good Comments

Legal Comments

Informative Comments

// Returns an instance of the Responder being tested.
protected 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 decision.
Clarification
Warning of Consequences
TODO Comments
Amplification
Javadocs in Public APIs

Bad Comments
Mumbling

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.
Redundant Comments

It's certainly not more informative than the code.
Misleading Comments
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.
Journal Comments

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.
Noise Comments
Scary Noise
Don't Use a Comment When You Can Use a Function or a Variable

Consider the following stretch of code:

// does the module from the global list <mod> depend on the

// subsystem we are part of?

if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))

This could be rephrased without the comment as

ArrayList moduleDependees = smodule.getDependSubsystems();

String ourSubSystem = subSysMod.getSubSystem();

if (moduleDependees.contains(ourSubSystem))

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.
Position Markers
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 instead.
Attributions and Bylines
Commented-Out Code

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.
HTML Comments
Nonlocal Information

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 is changed.
Too Much Information
In obvious Connection
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