A clever comment style

Comments are one of the most useful language features; in practically any programming language. Yet, they can become really a pain. Just consider the following example that I have seen quite often in different variations:

// now, return the difference between the two results
return result1 + result2;


// at this point x must not be negative
return a - b;

You could surely give me even better examples of counterproductive comments. In fact, this thread contains a long list of funny comments in the code.

Because such things really happen, some people come up with guidelines like, “never use comments in your code — make the code self explanatory.” While the direction looks sound, I would not go so far as to making it an ultimate rule.

I guess, we need to accept the shortcomings of comments; instead, let me show you a technique I was taught by my colleague that helps mitigate one comment-related problem.

The problem

We are only addressing one of a number of problems. It can be illustrated with the following example. Suppose I need to call a function written by someone else, and its name (for reasons beyond our control) is far from indicating the purpose. After performing an investigation, we share our findings:

// while the name does not suggest it,
// the following initializes the necessary devices:
// listener, translator, etc.
// this call cannot be moved down

bool ans = process_test_request();

if (ans)

Suppose, one year later, while fixing a bug someone decides to remove the call to go from this code and put it elsewhere, to a more appropriate place. Because people usually ignore comments, only one line gets removed, and the comment now — inadvertently — applies to the next line:

// while the name does not suggest it,
// the following initializes the necessary devices:
// listener, translator, etc.
// this call cannot be moved down

bool ans = process_test_request();

if (ans)

This problem occurs regardless of whether we put comments before or after the corresponding code. It would have been avoided if the comment were put in the very same line as the code: this way you remove comment along with the code. But for long comments, that do not fit into one line, usually this solution is not practical.

The solution

In such cases it is worth to consider the following style of commenting:

c.go(); /*
  while the name does not suggest it,
  the above initializes the necessary devices:
  listener, translator, etc.
  this call cannot be moved down

bool ans = process_test_request();

if (ans)

This way, when someone removes the line and forgets to remove the comment, he immediately gets a compiler error.

This entry was posted in programming and tagged . Bookmark the permalink.

20 Responses to A clever comment style

  1. But multi-line comments cannot be nested. I would advise against this. Also if a programmer can remove a line of code and not think about its surroundings he is a sloppy coder.

    • Finn says:

      Many, certainly not all, programmers are, in fact, sloppy coders.
      Many, certainly not all, programmers do, in fact, remove a line of code without thinking about its surroundings.

      When would nesting a multi-line comment be necessary? I’ve yet to see an instance in which such a case would be necessary; why would one need to comment a comment?

      “Nesting,” in multi-line comments, is typically seen as using indentation, empty lines, or even a hyphen/asterisk as nested bullets.

      Andrzej’s post, to me, attempts to outline practical comment formatting that causes the comment contents to be noticed where they might otherwise be inherently ignored (due to structure and formatting).

      • rk says:

        “why would one need to comment a comment?”

        I often encounter such a need when temporarily commenting-out a larger portion of code which already contains comments.

        • Thiago M. says:

          A good alternative to commenting-out large portions of code is the use of “#if 0 … #endif”. Those can be nested if needed, and also clearly distinguishes between comments and disabled (“commented-out”) code.

  2. Naveen says:

    I would prefer to provide the comment only where it’s really giving useful information to other coder and if they are ignoring then it’s not good. Specially in self explanatory code with relevant comments highlight the value of comment.

  3. Martin Moene says:

    …or the person first helpfully ‘corrects’ the peculiar comment-opening to be on a line of its own and then moves the code… without the comment.

  4. Shani Elharrar says:

    Maybe just wrap the call with a method that has the right name and put the comment inside the method (or outside it)

  5. tom tucker says:

    You don’t need comments if your write clean code.

    • Chris Glover says:

      Ha! If only that were true. Big systems always have edge cases that need to be documented in code because the reason for the edge case is marketing, business rules, or some other reason that doesn’t fit the model. Those things need to be commented otherwise one year later someone will come along and wonder why some weird piece of code exists in the strangest place and does some seemingly unrelated thing.

  6. Matthieu says:

    I would personally rename the c.go(), or if impossible because the author just prefer his creepy writting, then add a method init_devices() in which you put this single line, so your code become way more explicit without the need to change anything for the others. neither to add any extra comment, and the compilator can manage the optimization for replacing the method call by its content.

    • Nicolas says:

      Yes, renaming c.go is probably the best option here. (renaming field/method is something I do quite often when they don’t have the right name). Also note that since the comment refer to the go method, then it could (should?) be added just above the declaration of the go method, not here. If I go further, I could also split this comment in 2. This give us:

      //somewhere in the code
      class xyz
      initializes the necessary devices:
      listener, translator, etc.
      void go();

      //at the call place:

      c.go(); /* this call can not be moved down */
      bool ans = process_test_request();
      if (ans)

  7. quentin says:

    You may simply insert the comment block within the call’s braces. This way you really attach the comment to that particular statement. But it is considered ugly I guess…

  8. Evreyy says:

    Nice trick!
    Luckily, as of now, I’m not working on a big project where such bad situations occur. And I’d rather rename the whole function and replace all of the old names in calls, if possible. But yes, in cases where I can’t rename such stuff, I’d remember that trick.

  9. Ravi Terala says:

    This is where good code reviews come in. A proper code review should check for readability and maintainability in addition to logic correctness. For me, the code should describe the intent clearly and quickly and use as less comments as necessary. When the team embraces it, they derive great value out of code reviews.

  10. Martin Ba says:

    The idea is interesting, if, IMHO, too unusual formatting wise to really stick.

    What I would suggest in general, if such a lengthy comment is necessary to put the whole comment and the single line into a helper function.

    void init_devices(T c) {
    // bla bla bla

  11. Rob G says:

    Agree with @Martin Ba. What use is a comment if you sacrifice readabilty.

    We should all just grow up and, before commit, review our changes to ensure comments reflect the code.

  12. tpaszek says:

    double penetration; // ouch

  13. Pingback: (翻译)更聪明的注释方式 | cpp cube

  14. Pingback: CppCube » (翻译)更聪明的注释方式

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s