Re: commenting sub procedures

Explaining WHY the code does what it does should be the goal of program comments.

(I have been trying to reply to this thread and find myself typing and erasing over and over because every good reason and example I have for why and how one should comment is blatantly obvious .... which is probably why program comments are often times so sparse ... because when you are in the middle of writing code the logic appears to be blatantly obvious)

... Like this is obvious ....

* --- BUILD AN ETIMATE RECORD IF NECESSARY
*
C IF *IN66 = *ON
C AND *IN67 = *ON
c and jcjobn<= 9999
c or *in66 = *on
c and *in67 = *on
c and jcgpf2 = 'Y'
.....

All you need to do is figure out why *IN66 is on and why *IN67 is on and what it means when your JCJOBN is less than or equal to 9999 and you figure out why jcgpf2 = 'Y'.
.... It is obvious... isn't it?

Paul

-----Original Message-----
From: rpg400-l-bounces@xxxxxxxxxxxx [mailto:rpg400-l-bounces@xxxxxxxxxxxx] On Behalf Of Michael Schutte
Sent: Friday, March 23, 2012 8:38 AM
To: RPG programming on the IBM i / System i
Subject: Re: commenting sub procedures

And the documentation could do that exact same thing if all you do is explain the code instead of explaining why you did what you did.


Proc123 = bad. UpdateBOLCarrier is pretty clear. What do you document?
Procedure Updates BOL Carrier! Waste in my opinion.




On Fri, Mar 23, 2012 at 9:00 AM, Alan Shore<ashore@xxxxxxxx> wrote:

That would make perfect sense. Unfortunately, one person's
self-explanatory is another person's gobble-de-gook.

Alan Shore
Programmer/Analyst, Direct Response
E:AShore@xxxxxxxx
P:(631) 200-5019
C:(631) 880-8640
"If you're going through Hell, keep going" - Winston Churchill

-----Original Message-----
From: rpg400-l-bounces@xxxxxxxxxxxx
[mailto:rpg400-l-bounces@xxxxxxxxxxxx]
On Behalf Of Michael Schutte
Sent: Friday, March 23, 2012 8:54 AM
To: RPG programming on the IBM i / System i
Subject: Re: commenting sub procedures

Screw documentation... Make the procedure self explanatory.



On Fri, Mar 23, 2012 at 8:14 AM, Vern Hamberg<vhamberg@xxxxxxxxxxx>
wrote:

Hi Dave

I would put them in both the prototype AND the procedure. Prototypes
are often collected in a single /include member - you need the
comments there, too.

This is what the wizard in RDP does - it creates a comment header on
both. I find that useful myself.

Vern

On 3/23/2012 3:13 AM, Dave wrote:

Hi,

Where do you all put your comments on your sub-procedures? In the
prototype, or in the procedure itself? Ours have always been in
the prototype, which I have never liked as they are too far away
from the code. We haven't yet got V7.1 but given that the internal
procedure prototypes become unnecessary, it seems like comments
should not be placed in the prototype.

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


Disclaimer: This message contains confidential information and is
intended only for the individual named. If you are not the named
addressee you should not disseminate, distribute or copy this e-mail.
Please notify the sender immediately by e-mail if you have received
this e-mail by mistake and delete this e-mail from your system. E-mail
transmission cannot be guaranteed to be secure or error-free as
information could be intercepted, corrupted, lost, destroyed, arrive late or incomplete, or contain viruses.
The sender therefore does not accept liability for any errors or
omissions in the contents of this message, which arise as a result of
e-mail transmission. If verification is required please request a
hard-copy version. Any views or opinions presented are solely those of
the author and do not necessarily represent those of the company.
--
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.