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
  • 839
  • 1
  • 6
  • 19
  • 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

1 Answers1

4

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

To this though, this is not uncommon for new programmers to do; some I've seen as an example:

if (some_array[i - 1] == 0) { // remember INDEX STARTS AT 0!!
    some_array[i - 1] = 1; // set to 1 if it equals 0
}

What's important to teach is what a comment is intended for: to annotate.

As an example, when you read certain materials there might be a footnote1 for a certain word, but2 you3 wouldn't4 see5 a6 footnote7 detailing8 every9 word10.11 Since the author of the material expects the reader to have a basic knowledge and understanding of the syntax and structure of the language in order to basically read it, but might not understand the specificities of their field. Or in the case of source code, one would annotate an area of code that might not make sense to the casual reader who has a basic understanding of the language, as an example:

uint8_t temp;

// Rotate first row 1 columns to left  
temp           = (*state)[0][1];
(*state)[0][1] = (*state)[1][1];
(*state)[1][1] = (*state)[2][1];
(*state)[2][1] = (*state)[3][1];
(*state)[3][1] = temp;

Part of learning to program is learning to read code and understand what it's doing regardless of what the comments say, because the compiler doesn't care about the comment.

But it's also important to understand how useful a comment can be at 2 AM, even in your own code.

Hope that can help you and your students.

1 - that explains a little more
2 - preposition-except
3 - not me
4 - 1 word meaning would not
5 - observerate
6 - the first letter of the alphabet
7 - a footnote .. see footnote7
8 - to explain more, or make vehicle look nice
9 - all encompassing
10 - seriously, it would be a nightmare if books were commented like some code
11 - FULL STOP!!!!

Nawaz
  • 341,464
  • 111
  • 648
  • 831
txtechhelp
  • 6,377
  • 1
  • 29
  • 37