Re: Documenting code changes

[Vernon Hamberg <vhamberg@xxxxxxxxxxxxxxx>]

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