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.