RE: commenting sub procedures

For documenting a procedure that is exported; I would only put the
comments in the copy book that contains the prototype. For internal
procedures I am more likely to comment on the procedure interface, as
few people will actually look to the Prototype for the documentation
when they can just search for the procedure. A few of us here use the
method of documenting the procedures like Alan Campin's example.

I also agree that you should comment the actual code, but that comment
should describe the Idea behind the code, not the code itself. I have
ran into the issue countless times where you add very detailed comments
to a program, then the next person comes in after you and changes the
whole program and makes the comments obsolete. There are also some
people who will never read your comment, no matter how detailed it is.

Speaking of filtering to PRs here is the regular expression I have been
using for that purpose.
^(.){5}D(( )*[A-Za-z](.)+(\.\.\.)$|((.){15}( ){2})P(R|I))


Chris Hiebert

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

Dave

I understand not duplicating comments. If your prototypes are right next
to your procedure, then there is not much point in writing the comments
twice.

But even in a single source, usually I have all prototypes grouped
together before any of the procedures. If I am looking at the
prototypes, I do not want to have to find the procedure in order to see
what it is about.

This enters the world of religion, I suppose!! And in some cases, each
person's beliefs are equally valid.

It is interesting to me that WDSC/RDP lets us filter by procedure but
not by prototype - not easily, at any rate. I think there is a way to
group by procedures, such as filtering on the PR identifier.

Vern