0

I'm teaching a C++ programming course for the first time in a while and, somewhat based on the elementary book examples, I find that students want all of their comments to be end-of-line like so:

for (int count = 1; count <= days; count++) {   // Loop for each day
    organisms += organisms * increase;          // Compute organisms
    cout << organisms << endl;                  // Print out organisms
}

In contrast, I'm trying to get them to use dedicated comment lines that summarize several lines of code for this purpose:

// Update & display organisms for each day
for (int count = 1; count <= days; count++) { 
    organisms += organisms * increase;          
    cout << organisms << endl;                  
}

Is there a proper name for this latter, not-end-of-line comment styling?

Daniel R. Collins
  • 893
  • 1
  • 8
  • 22
  • Not sure about naming convention, but show them the example `i=i+1; // increment i` Which is a perfect example - comment is longer than the code and doesn't tell you anything more than the code. The interesting bit is WHY do we need to increment `i`? – John3136 Oct 31 '16 at 03:22
  • "*Those comments which start at code indentation*" or TCWSACI for short – Barmak Shemirani Oct 31 '16 at 03:30
  • 2
    Off topic, but shouldn't we prefer semi-open range on loop variable? –  Oct 31 '16 at 03:31
  • 1
    Tell them being trying to be specific is a never-ending tasking. For example, `"Compute organisms"` doesn't really tell us the reason as to how exactly the computation is done. So a more specific comment would be *"Compute organisms by multiplying the current `organisms` with `increase` and then adding it to the current `organisms` and update it with the new value."* .. (continued) – Nawaz Oct 31 '16 at 03:32
  • (continued)... and somebody might come and still find ways to improve the specificity. So it seems it is a never-ending task.. or at least tedious and timesome to follow. So it is better to be vague in the comment and put a summary instead, as long as the code speaks the rest (i,e the details) very clearly. It has one more advantage: if the details of the code changes overtime, while keeping the goal unchanged, the comment needs not be changed. **The general principle should be : the comment need not be changed with every little change in the code.** – Nawaz Oct 31 '16 at 03:41
  • 1
    I call those comments redundant and uninformative. They do nothing to enhance the readability of the code for any _competent_ programmer. Worse, there is no compiler checking of comments which means those comments can deviate from code making actual behaviour vs. intended behaviour ambiguous. As for the 2nd code block the comment prefixing the code is a strong indication the code belongs in a separate appropriately named method. – Disillusioned Oct 31 '16 at 03:42
  • If in your course you're going to "teach comments". Let me suggest that there's no point in fussing about different commenting styles. A career programmer will be expected to follow the standards of the code-bases they work on regardless of _your personal_ preference. You'd do better to teach the differences between good comments and bad comments. See http://stackoverflow.com/q/209015/224704 – Disillusioned Oct 31 '16 at 05:02

2 Answers2

5

There's not a specific naming convention to the comment structure you ask beyond the // to mean a line comment, and how to comment is something that is usually left to the style guide (if any) of the source in question. That wiki article even states:

The flexibility provided by comments allows for a wide degree of variability, but formal conventions for their use are commonly part of programming style guides.

Commenting style does not have a syntax naming convention beyond block comments (sometimes called C-style commenting), line comments and the such, unlike coding syntax conventions (like OOP, functional, lambda expressions, etc.).

This is because a comment is intended, typically, to annotate something, and not as a function of the code itself.

I say typically because you can use comments for things such as copyrights, or to help generate documentation (via something like JavaDoc style)

Again though, these are "styles" of commenting, and not a syntactical structured name.

Is there a proper name for this latter, not-end-of-line comment styling?

No. Again this is because comment style, structure and content is left to the author. One could even follow iambic-pentameter in their comments if they so wished.

If you must give it a "name", you could call it a single line concise functional comment as that what your example is; a single line comment that is concise and describe what the functional part of that code does.

Ultimately you're trying to teach your students what the purpose of comments really are for, and a career programmer doesn't need every line of their code commented, much like a dictionary doesn't have every part of a definition annotated.

txtechhelp
  • 6,625
  • 1
  • 30
  • 39
  • @DanielR.Collins .. just updated the answer .. long story short; no, commenting doesn't have a syntactical naming standard, simply either "block or line". Even the [linux kernel source comment style](https://docs.kernel.org/doc-guide/kernel-doc.html) makes no mention of anything more than how to format the comments and what to include. – txtechhelp Jul 25 '22 at 22:12
  • 1
    @DanielR.Collins works for me! I'd love to see a "standard" regarding comments as well, and love to learn (of course I'm reminded of good ol' [Randal's standards](https://xkcd.com/927) at that point, lol) .. hope your students learn a little something! – txtechhelp Jul 26 '22 at 02:52
0

The Java Checkstyle tool refers to this as a trailing comment.

Their documentation references Steve McConnell's Code Complete, which argues against the practice, and refers to them as endline comments. Part of the section they quote from McConnell:

  • Endline comments tend to be hard to format... It takes time to align them. Such time is not spent learning more about the code; it's dedicated solely to the tedious task of pressing the spacebar or tab key.
  • Endline comments are also hard to maintain. If the code on any line containing an endline comment grows, it bumps the comment farther out, and all the other endline comments will have to bumped out to match. Styles that are hard to maintain aren't maintained....
  • Endline comments also tend to be cryptic. The right side of the line doesn't offer much room and the desire to keep the comment on one line means the comment must be short. Work then goes into making the line as short as possible instead of as clear as possible. The comment usually ends up as cryptic as possible....
Daniel R. Collins
  • 893
  • 1
  • 8
  • 22