RE: commenting sub procedures

Boy, does that bring back a memory. The magic number was 10000.01, I do not miss the 36!

-----Original Message-----
From: rpg400-l-bounces@xxxxxxxxxxxx [mailto:rpg400-l-bounces@xxxxxxxxxxxx] On Behalf Of John McKee
Sent: Monday, March 26, 2012 12:08 PM
To: RPG programming on the IBM i / System i
Subject: Re: commenting sub procedures

I had an instructor in college who faulted a FORTRAN program I had turned in. I had already been doing FORTRAN programming and needed the class. The program was simplistic beyond belief. Did a single calculation and printed the result.

My line of code was:
GROSS = HOURS * RATE

His complaint was that a comment was needed there. In the example above, a general series of comments was in place to describe what the program was to do.

Point being that, IMO, comments should describe >what< is intended by a sequence and explain any odd segments, without just repeating the code. Seeing something bizarre like the old trick of multiplying a number by the magic RPG number (which I have forgotten) to change the order of digits in a numeric representation of a date DOES need a comment (but that particular multiplication technique is likely best avoided in the first place.

John McKee

On Mon, Mar 26, 2012 at 9:56 AM, Charles Wilt <charles.wilt@xxxxxxxxx> wrote:

Comments lie...

Trust but verify...

Charles

On Mon, Mar 26, 2012 at 10:35 AM, Jerry C. Adams <midrange@xxxxxxxx> wrote:

I can't say that I disagree.  However, I have seen the opposite
problem; i.e., the program logic changes, but the documentation isn't
changed.  More than once I have tried to make sense of a program in
which I could see that it was doing one thing, but the documentation said something different.

--
This is the RPG programming on the IBM i / System i (RPG400-L) mailing
list To post a message email: RPG400-L@xxxxxxxxxxxx To subscribe,
unsubscribe, or change list options,
visit: http://lists.midrange.com/mailman/listinfo/rpg400-l
or email: RPG400-L-request@xxxxxxxxxxxx Before posting, please take a
moment to review the archives at http://archive.midrange.com/rpg400-l.

--
This is the RPG programming on the IBM i / System i (RPG400-L) mailing list To post a message email: RPG400-L@xxxxxxxxxxxx To subscribe, unsubscribe, or change list options,
visit: http://lists.midrange.com/mailman/listinfo/rpg400-l
or email: RPG400-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives at http://archive.midrange.com/rpg400-l.