Effective Comments

Effective comments are not just comments. Even though comments are used to annotate the programming source code, we can divide them to 5 different kinds of comments

1. Repetition of the code restates what the code does in different words.

   Example:

   // call getScreen method EmpRec.getScreen();

   
   
2. Explaination of the code used to explain complicated, tricky, or sensitive piece of code.

   Example:

   // getScreen() is just a data entry screen EmpRec.getScreen();

   
   
3. Marker in the code reminds the programmer of what to do.

   Example:

   //*** change getScreen() to getInfo() later EmpRec.getScreen();

   
   
4. Summary of the code distills a few lines of code into one or two sentences.

   Example:

   // update EmpRec EmpRec.read(currentEmp); EmpRec.getScreen(); EmpRec.write(currentEmp);

   
   
5. Description of the code's intent explains the purpose of a section of code.

   Example:

   // get current employee information EmpRec.read(currentEmp); EmpRec.getScreen(); EmpRec.write(currentEmp);

Which one is effective comment? Strive for intent comments, and you may even settle for summary comments but try to avoid the other kinds:
Repetition comments are useless,
Explainatory comments mean the code is not easy to understand
Marker comments mean the code is incompleted.

If you are interested to be a better programmer, study the book "Code Complete" by Steve McConnell.

Home | Syllabus | Lectures | Assignments | Coding Conventions | Links