Re: commenting sub procedures

Most of my work involves writing procedures where the procedure code itself
won't be seen by our customers - it's exported from a service program -
all they will see is the procedure prototype. Therefore I need to ensure
that not only do I document both the prototype *and* the procedure itself,
but that they each have appropriate documentation

In these cases, the prototype will actually typically have
*more*documentation than the procedure itself, since it needs to be
thoroughly
understood by the end-user. Therefore they need to know all the possible
parameters and how they should be used, any possible return values, and
sometimes even a quick 'sample', to show how the procedure should be called.

By comparison, in many of those cases, the procedure itself will have
minimal documentation, since any developer who has to maintain it should
know what they're doing before they start messing with the code.

It obviously helps that I tend to write small procedures which are as much
'stand-alone' as possible, meaning that there's often little need for
explanatory documentation.

Of course the rest of my work involves maintaining 20+ year-old PL/I
programs with inconsistent indentation and cryptic acronyms sprinkled
throughout... :(

Rory

On Fri, Mar 23, 2012 at 3:59 PM, Sam_L <lennon_s_j@xxxxxxxxxxx> wrote:

This could be a good conversation. At the risk of starting a religious
war, I'll toss in my opinion.

I generally agree with David, but would take a slightly different
approach. I prefer bullet points over what is often "Stream of
conscious" thinking. And bullet points on separate lines are easier to
edit in SEU or RDP. Also, parameters should be documented.

// UpdateBOLCarrier
//
// Updates the customer invoice file with the BOL carrier and
// returns the carrier cost of the invoice.
// - Verifies BOL carriers in valid and current and that the
// carrier has a valid certification
// - Verifies invoice exists for the customer
//
// Returns:
// 0 Success
// 1 Failure
//
// Parameters
// In S 10,0 Customer number
// In S 7,0 Invoice number
// In P 5,0 BOL carrier code
// Out P 11,2 Carrier cost for the invoice
//

Obviously this is a contrived example and is unlikely to reflect the
reality of any real code.

Sam

On 3/23/2012 9:45 AM, David Gibbs wrote:

A procedure's documentation should be more than just a title ... it

should describe, in high level detail, what it's doing.

// UpdateBOLCarrier
//
// This procedure updates the BOL Carrier by identifying the appropriate
// carrier from the BOL file, verifying that it is valid and the carrier
// has a current certification record, and updating the customer invoice

file.

//
// NOTE: BOL Carrier = Bill Of Lading carrier
//
// Update history:
// 3/26/12 DMG - Fixed certification logic to use new auth records

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