Comment Style in OpenCV

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.

    Good Comments-Explanation of Intent

  • Clarification

    Good Comments -Clarification

  • Warning of Consequences

    Good Comments - Writing of concequences

  • TODO Comments

  • Amplification

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

    Bad Comments - Mumbling

  • Redundant Comments

    It's certainly not more informative than the code.

    Bad Comments - Redundant Comments

  • 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

    Bad Comments - Noise Comments

  • Scary Noise

    Bad 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

    Bad Comments - Position Markerspng

  • 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

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

    Bad Comments - Non Local Information

  • Too Much Information

    Bad Comments - Too Much Information

  • In obvious Connection

    Bad Comments - 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

Example of a code full of comments

Good Comments - Generate Prime

The same code but this time refactored

Good Comments - Generate Prime Refactored


Clean Code,A Handbook of Agile Software Craftsmanship, Robert C. Martin



All Categories