Re: Documenting code changes

+1

i didn't go into SCM packages - used as David suggests is likely a best practice.

Still, there will be those that want a local comment about a change - and that can be the kind of thing you say, larry - the "important" ones.

As to order of changes in a comment header - I like that suggestion of most recent at the top - I think IBM does that in the include members in QSYSINC.

I do see places, though, that have a lot of code from a long time since that put the latest at the bottom - I suppose it is easier for treating it as a narrative.

Vern

On 9/27/2013 11:29 AM, DrFranken wrote:

ABSOLUTELY Agree with David. All those comments around code make it
very hard to read and more importantly understand. Back when I coded a
lot there would be times my brain couldn't filter out the commented code
so understanding it was hard. As Vern pointed out yes RDi can filter
those out but then you also lose the important comments that say: "This
bit of code does this important thing in this particular way...."

I am also a HUGE fan of most RECENT change comment on TOP at the top of
the program always visible upon opening the source. This way the FIRST
thing I see is what changed most recently. In this way when there is an
issue I know the most likely part of the code will be identified right
there. It drives me nuts when vendors require some huge code block
about copyright etc etc etc making me roll down 2, 3, 4 pages to get to
the comments and then another page or two to get to the bottom of the
comments.

Noting the change number on the lines affected is fine and that would be
in col 1-5 (RPG) or on the far right (CL) if it were my choice.


- Larry "DrFranken" Bolhuis

www.frankeni.com
www.iDevCloud.com
www.iInTheCloud.com

On 9/27/2013 12:22 PM, David Gibbs wrote:

On 9/27/2013 10: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.

I don't like that technique ... the code gets WAY too cluttered with a result of being hard to read.

Personally, I perfer to have a change control system that does detailed source code archiving ... that way we can compare the various versions and what issue resulted in the change.

david
(who works for PTC, makers of the Implementerchange control system, in addition to running midrange.com)