4.3. Other Comments

If you have something important to say about how a function works, say so in the function body. Use paragraph comments. For example, write a paragraph of comment followed by a paragraph of code that accomplishes what the paragraph describes.

Feel free to document what variables are. But again, do it in a paragraph commment.

You can improve readability by setting off comments. For example,

  //---------------------------------------
  // First rotate the structure to the left.
  //---------------------------------------

  code to rotate the structure to the left

  //----------------------------------------
  // Now fill the left-hand part with zeroes.
  //----------------------------------------

  code to fill the left-hand part with zeros
Readers often want to avoid reading everything and they seek out comments that identify a section of interest. Comments that are easy to locate make that easier.