A long time ago, in a far-away classroom I was seemingly forced to write copious amounts of documentation in a FORTRAN class just for a few lines of code. It didn't help that I was just learning how to keyboard (type) and that I didn't understand why pseudo code was also required by my nameless, faceless teacher. Yes the experience was so ardous that I can't even recall the name of the man I should be thanking right about now.
Oh to be sure, I still don't like documenting VBA code in Excel. Yet after returning to a lengthy and involved Excel reporting package that I wrote over two years ago the documentation saved me many hours of toil and trouble.
The following is an example what I normally like to put at the beginning of each subroutine. The overall flow of what the routine is doing, any special input/output variables or noteable arguments, and subroutines or functions that are used or called within the routine.
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ' This error check subroutine looks at a number of conditions that ' would cause the program to fail, and provides the user with an ' appropriate message. It is called by either the Run Report or ' Run Reports DT routine and uses the argument SheetName, which is ' the appropriate sheet name from the calling program. This routine ' uses the function InvalidDatesInRange, which may call the InputDates ' routine if true. These both use the SheetName argument. This ' routine also uses the function EarlyDatesInRange, which may call ' the EarlyDates routine if true. ' ' CHECKS IF INPUT DATA EXISTS ' CHECKS FOR INVALID START DATE ' CHECKS FOR INVALID END DATE ' CHECKS IF THERE ARE INVALID DATES IN THE INPUT DATA ' CHECKS FOR DATES BEFORE THE EARLIEST DATE SETTING ' CHECKS IF THERE IS ANY MATCHING DATA ' CHECKS FOR ANY FUTURE DATE ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Within the subroutine I document segments of code to allow the reader to follow the logic. I try to keep it short and only break out the pseudo code to map out large projects.