The Beauty of a Complicated Function Comment Header (Classic ASP)

Without boring you with details, I wrote an application back in 2003 for a medical billing company. Their team was extremely small, so when I left the project, I made sure they had some very clear documentation. The function headers were my favorites. Here's an example.

Well written comments that are clear and easy to read is very important to code maintenance and reducing technical debt incurred as old applications lose their orriginal developers.

' =============================================================================
' *** AddCertifications()
' -----------------------------------------------------------------------------    
'
'    PURPOSE:    Adds Certification information for a patient into the
'                CN_CERTIFICATIONS table
'            
'    INPUTS:        
'        pCnn        (Conn)    ADODB.Connection object
'        pPlanID     (int)    Insurance Plan ID from CN_INSURANCE_PLANS
'        pStartDTM   (date)
'        pEndDTM     (date)
'        pAuthNum    (str(50))
'        pDaysAlert  (int)    same as "ALERT_DAYS_PRIOR_TO_END"
'        pSessAlert  (int)   same as "ALERT_SESSIONS_LEFT"
'        
'    OUTPUTS:    
'        Any errors regarding datatype or missing values in required fields
'        - OR -
'        New CERTIFICCATION_ID
'
' -----------------------------------------------------------------------------    

Function AddCertifications(pCnn, pPlanID, pStartDTM, pEndDTM, pAuthNum _
            , pDaysAlert, pSessAlert)

End Function

' -----------------------------------------------------------------------------