Differences

This shows you the differences between two versions of the page.

--- guides:programstyle:comments [2020/08/18 11:12] – [Comments Before Functions] wikiadmin
+++ guides:programstyle:comments [2024/07/25 15:01] (current) – external edit 127.0.0.1
@@ Line 80: / Line 80: @@
 ==== Comment Placement in Code ====
 Single line comments should be placed before sections of code which need explanation.
+Comments should begin in line with the code which is being documented:
+An acceptable example:
+<code c++>
+    // Read the input from the user and ignore any extraneous output
+    cin >> word;
+    cin.ignore(1000,'\n');
+</code>
+An unacceptable example:
+<code c++>
+// Print a line of the story filling in the blank
+       cout << line1Part1 << nounResponse << " " << line1Part2 << endl;
+</code>
+Comments should generally not be placed on the same line as code.  This guideline may be violated when declaring variables.
+The following example is not acceptable.
+<code c++>
+       cout << endl;    // done with output, print an endl
+</code>
+Use comments to supplement the understanding of major sections of code.  Only rarely should comments be used on every line of code.  The following is not an acceptable use of documentation.
+<code c++>
+// Get the noun from the user
+noun = GetWord("a noun");
+// Get the adjective from the user
+adjective = GetWord("an adjective");
+// Get the action verb from the user
+actionVerb = GetWord("an action word");
+</code>
+The code above is mostly self documenting due to identifier choice, so a single comment would be more appropriate
+<code c++>
+// Get the words from the user
+noun = GetWord("a noun");
+adjective = GetWord("an adjective");
+actionVerb = GetWord("an action word");
+</code>
+Finally, most comments in code should employ a c++ style line comment.  This allows the programmer to comment out large blocks of code with c style comments.
+==== Comment Contents ====
+Comments should describe the code, however comments should not repeat the code.
+An acceptable example:
+<code c++>
+// use the Pythagorean theorem (a^2+b^2 = c^2) to find the length of the third size.
+hypot = sqrt(sideA * sideA + sideB * sideB)
+</code>
+An unacceptable example:
+<code c++>
+// c = sqrt(a*a + b*b)
+hypot = sqrt(sideA * sideA + sideB * sideB);
+</code>
+In the above example, the comment provides NO additional information.  It is a duplication of the code.  This could be very detrimental if the original code was in error and later corrected, but the comment was not updated.  In that case, a future reader of the code would be further confused by the comment.
+In general, comments should support a knowledgeable programmer.