Place Note or Comment in Source Code

No matter how human friendly the computer languages, we still needed to leave note/comment in source code. Even the expert programmer will spend time and scratch head to study own codes that programmed few months ago, if don’t leave proper comment.

Here is Do and Don’t of Comment usage:
1)    Do place comment block in source code file header.
   -   Header comment is recommended to keep information about:
      i.    The program or function name
      ii.   The description of program or function does
      iii.  The author’s name
      iv.  The revision and history (in short)
      v.   Additional notes as deem needed
2)    Do use comment to tell a section of code does.
   -   Simple and clear explanation is always preferred.
3)    Do keep comment up-to-date as coding change.
   -   Keep discipline to update comment as code changes. Avoid leaving “trap” for other and even own-self.
4)    Don’t use comment for simple or self-explanatory code.
   -   Never over do with comment, until become burden for other people to read, and also causing own-self source code maintenance trouble in future.
5)    Do use comment to tell a specific/unique code method.
   -   Some code statement need special attention and comment will help to keep memory intact.

Comment in block by slash-star (/*) as begin and end with star-slash (*/)

/* Start your comment here…
…  in block …
*/

 
C++ bring back the feature of single line comment, by double-slash (//); Java also incorporate this useful feature.

// Single comment line here…

Using of single line comment “REM” with meaning as remark. An apostrophe (`) can also be used as fast typing replacement.

REM Here is single line comment
REM … next comment…

` Easier to be used to…
` … construct a …
` … comment block.

Note & tips: During code debug or short term code modification or quick modify of other people code (in less/not fully understanding situation), “comment-out” single line or block code will help to preserve original coding (maybe use for undo in later), in mean while we can introduce simple variation code to check for fix/enhancement.

Discussion in Forum