Re: commenting sub procedures

[Sam_L <lennon_s_j@xxxxxxxxxxx>]

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