Everyone knows that best practice tells us to put comments into our code/models; some of us do.  The question for today’s blog is “what makes a good comment?”

The good, the bad and the just simply useless

NOTE: all examples of “bad comments” are taken from real-world experience.

1. Do not repeat the information in the model:  
   For the given line of code:
   output = input * 2;
   1. Bad comment: /* The output is equal to 2 times the input */
   2. Good comment: /* Investment pays two times the deposit */
   3. Useless: /* Multiplication operation */
2. Explain why something is done in a given way:
   For the given line of code:
   bound = min(upper,max(lower,length));
   1. Bad comment: /* Run min/max functions on length */
   2. Good comment: /* Limit ouput between upper and lower bounds */
   3. Useless: /* Bound value is bound */
3. Are clearly written:  Comments should be written in the native langue following standard grammatical rules.  Avoid slang and abbreviations.
4. Are “as long as they need to be”:  Comments do not take the place of requirements.  They are in place to explain part of the model/code.  As such they should be written so they explain the concept and no more.

Why we comment?  What comments can’t do…

Comments aid people in understanding what the model or code is intended to do.  Comments need to be maintained as the source is updated; there is nothing worse then a 3 year old comment that has no relationship to the current object.  Finally, they cannot take the place of well-written code.    (In all honesty, I have no idea what the screenshot that follows does….)