Re: commenting sub procedures

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