Re: commenting sub procedures

I put the following each one of subprocedures. It clearing delineates the
beginning of a procedure and provides documentation on how parameters are
used.

* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

* GetTimestampFromAlpha

* This function gets the timestamp from JDBC character timestamp.

* Input - Timestamp in alpha format from JDBC

* Out - None
* In/Out - None

* Returns - Timestamp

* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

p GetTimestampFromAlpha...

p b

d pi Like(StdTms)

d InJDBCTimestamp...

d 26a Varying

d Value



On Fri, Mar 23, 2012 at 4: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.