Re: Documenting code changes

Hi, Cyndi:

To add to what others have suggested ...

Learn to use the CMPPFM command (option 54 of PDM). CMPPFM can produce a
"delta" -- an *OUTFILE member that contains exactly what has changed
between any two versions of source members. For example:

CMPPFM NEWFILE(DEVSRC/QRPGLESRC) NEWMBR(mbrname) +
OLDFILE(PRDSRC/QRPGLESRC) OLDMBR(mbrname) +
CMPTYPE(*LJNE) RPTTYPE(*DIFF) +
OUTFILE(PRDARCHIVE/mbrname) OUTMBR(VRSN0002 *ADD)

Study the "delta" produced in the output file member. With this
approach, you could store only the "deltas" for all versions of source
members: with delta member names like VRSN0001, VRSN0002, VRSN0003, etc.
-- as many as you want. (Notice that the name of the outfile is based on
the original member name in the above example.)

Also notice that the "delta" is bi-directional ("works both ways") --
suppose you have the current source for Version 3, you could use the
delta to recreate Version 2 by "reversing" the delta for "version 3" --
"Inserts" become "Deletes" and "Deletes" become "Inserts". (This is a
very important point to understand when using deltas, even the Unix DIFF
tool has this property.).

This way, you can maintain a complete version history without having to
keep full copies of every version.

You could also print the report produced by CMPPFM and keep them in a
binder, to show the auditors, when they want to know "what changed."

Of course, any comments you add to the header describing the changes
will show up in these delta reports. :-)

All the best,

Mark S. Waterbury

> On 9/27/2013 11:54 AM, Cyndi Bradberry wrote:

Hi,
In the past, we have documented at the top of the program the date, ticket # and a description of a change. Now we are being told to put the ticket number in the first 5 positions, copy the line we are changing, commenting out the original line and editing the new. In CLP, /* */ to enclose the ticket number on the line being changed.

But I cannot get anyone to explain how long this remains in the code. I don't have a problem with commenting out and entering new lines, but when I go in to maintain the program next, I generally want to clean up (delete) the unused lines of code to make for better readability. When making large changes, I also make backup copies of the source member just in case I have to go backwards.

Can anyone point me to a best practices for documenting code changes ? This would have to cover RPG IV and Free and CL programs. We are working towards a SOC 2 Type 1 compliance.

TIA,
Cyndi B.
Boise, ID