RE: Documenting code changes

Hi Cyndi,

I'm afraid I haven't needed to bother with that for some time now... We do put comment tags at the top, and some developers will leave commented out lines in source, but my policy is, once we know that the program has stabilized, then the commented lines get ripped out.

I use our change management software to track the deltas, as each version of the source is retained by the source archives in TurnOver. The product exposes the source compare features to these source archives, allowing easy review of the actual source changes involved in each change ticket. I think it's much easier to work with clean source.

-Eric DeLong

-----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