- 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
- 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.
a line after each new internal subroutine (GOSUB) with a description.
Keep description short and meaningful.
/* This process updates the accum units on the
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.
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.