Function and Subroutine Headers

A function header is a comment that describes what the function does and summarizes its interface. The description should focus on what the function does, although for complicated or longer functions it might be appropriate to summarize the how as well. All nontrivial functions should have function headers, and headers are also recommended for nontrivial event handlers.

Here is an example function header:

' **************************************************************
'
' Synopsis      Create the event queue, and attach
'               an event handler to it.
'
' Parameters
'
'   pcbiNewWinProc          (I) Address of the event
'                               queue callback function
'
' Nonlocal Data
'
'   hwndPiEventQueue        (O) Event queue handle
'   pcblPiEvQueueOldWinProc (O) Event queue default
'                               window procedure
'   lPiFSMEventMsg          (O) Event message number
'
' Description
'
' This is where we create the event queue and attach a
' callback function to it to handle our FSM events.
'
' The event queue is built around a private window that
' we create here. We subclass the window to hook
' pcbiNewWinProc onto it and then register a custom
' message number that we will use to send messages to it.
' The pcbiNewWinProc parameter is a pointer to a VB
' function obtained with the AddressOf operator.
'
' **************************************************************