RE: Documenting code changes

I don't think that there is one simple solution for all your changes.

For tiny changes, commenting out the old stuff and adding a new line is great! For example, if replacing a hard-coded network path with a variable path:

The "004" is NOT the ticket #, rather the source version # for this particular CL. For example, the following is the 4th change to this pgm since pgm creation. At the top of source is a comment relating the "004" to the ticket #.

/*@004D CHGRDIR RMTDIR('CorpNetworkServer/FTP/Receive/Test') */
/*@004A*/ CHGRDIR RMTDIR(&NET_DIR)

The above is intuitive and is helpful for future pgmrs (or myself as my memory weakens) when it is looked at in 6 months.

For a larger mod such as removing 500 lines of code and replacing with a callable reusable pgm, go ahead and delete the 500 lines and key a comment stating so much.

When people are browsing and searching thru code, it is unlikely that they will have the time to refer to archives in general. Depends on how much time is available and how bad they want to know what "was". Having small changes documented in the source can really be a time saver.






-----Original Message-----
From: midrange-l-bounces@xxxxxxxxxxxx [mailto:midrange-l-bounces@xxxxxxxxxxxx] On Behalf Of Cyndi Bradberry
Sent: Friday, September 27, 2013 10:55 AM
To: 'Midrange Systems Technical Discussion'
Subject: Documenting code changes

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