|
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 zerosReaders 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.
| Margin comments are placed in the right margin after a line of code. They tend to yield long lines and are often of little value. Do not use them, except when they are short and improve readability. If you have something worth saying, do not marginalize it, but write it in a comment line or paragraph just before what it describes. You can describe more than one variable in a single comment where it is sensible. |
|