On 28/05/2009, at 11:12 PM, David FOXWELL wrote:
* Interface for the procedure MySubProcedure.
D MySubprocedure PI
Part of your search problem is this sort of useless comment. It serves
absolutely no purpose. The code tells me exactly the same thing. This
is like old RPG III code with a comment that simply repeats the code.
For example:
C ADD 1 COUNT Increment count
It's just pointless. Removing useless comments will reduce the number
of false hits when searching.
As for your other concerns and the various responses from people about
specifying the procedure name in three places in the code: well you
have a choice. The compiler team were about as flexible as they could
be on this. They REQUIRE the presence of a P Begin and a P End (and
you can omit the P End if you compile with GENLVL(20) but I don't
advise that). The PI is only necessary if parameters or a return value
are needed. They REQUIRE a name only on the P Begin--it can be omitted
from both the PI and the P End. They ALLOW a name to be specified on
all three but if you do that then the name must be the same.
I see distinct coding advantages to specifying the name in all three
places.
Get your shop standards set up such that they reflect the way you and
your team want to code. For example:
Procedures:
o All procedures will have a comment block explaining the purpose of
the procedure, its input, output, and return values. See procedure
comment block in Appendix C.
o All procedures will have a P Begin and a P End. Do not specify the
procedure name on the P End.
o All procedures will have the name specified on the D PI
specification.
Comments:
o Comments must illuminate, not reiterate. They should tell WHY
something is done not WHAT is being done.
o Do not simply comment what can be read in the code.
I'm a bit retentive about this sort of thing. I specify the procedure
name on both the P Begin and P End lines for the same reason I specify
ENDIF, ENDDO, and ENDSL instead of simply using END for all of them.
The compiler will catch out-of-sequence procedure end statements. I
think that's a good thing. Putting the name on the P End also allows
me to easily find the end of a given procedure by searching for the
last occurrence (this may be less useful in *PGM source but is very
useful in *SRVPGM source).
I also put the procedure name on the D PI because I think it looks
weird without it and it makes it easy to duplicate from the PR.
I would suggest that your standards be either:
o Names on all three specifications (so you can easily find the end)
or
o Name on the P Begin (required by compiler) and on the PI (so it can
be easily duplicated from the PR).
any other suggestions seem like nonsense to me.
I note that now procedures can have F-specs and that they go between
the P Begin and the D specs my choice of naming BOTH the P Begin and
the D PI makes more sense.
Regards,
Simon Coulter.
--------------------------------------------------------------------
FlyByNight Software OS/400, i5/OS Technical Specialists
http://www.flybynight.com.au/
Phone: +61 2 6657 8251 Mobile: +61 0411 091 400 /"\
Fax: +61 2 6657 8251 \ /
X
ASCII Ribbon campaign against HTML E-Mail / \
--------------------------------------------------------------------
midrange.com
