COMMENTS

  • Meaningful comments should can be added to programs, including leaving in commented out code.
  • Remove all comments from previous versions when you create a new version.
  • If you consider a comment is needed, put it in, even if it includes a version number. (But do not simply put version x starts here, then version x finishes here).
  • If you need to delete line(s) of code, and you think it would assist someone else that may read it to leave the lines in, then comment them out and add a comment - "The following lines were removed because...".  The next time the program is changed, these will be removed as above.
  • The end result should be that the program has meaningful comments where you consider comments to add value.
  • When a program is changed ensure the program is backed up and the version number on the program is changed with a change date and developers initials.  Add a meaningful description to explain the changes.  Add the upgrade number to the description.
  • Create a line after each new internal subroutine (GOSUB) with a description.  Keep description short and meaningful.

UPDATE_POLICY:

/* This process updates the accum units on the policy */

  • Indent the comments in line with the coding, i.e. if comments are added into a CASE statement, then indent the comments in line with the CASE statement code.

BEGIN CASE

   CASE POL_REC<PO$UL_OPTION> = 1

       *Caters for Fixed face amount

         FACE_AMT = POL_REC<PO$FACE_AMOUNT,COV_NO>

  • Do not add comments in programs to show changes.  Use the compare capability utility to determine the changes between the current and previous of the program.
  • When the program is changed, all relevant comments should also be changed (out of date comments are worse than the absence of comments).
  • Add blank comment lines where appropriate to make the code easier to read.