Visual Basic —

File Headers

Every module should have a header that sits as a comment in the module's definitions area. The header identifies the module and summarizes the external interfaces to it. Here is an example module header:

  ' **************************************************************
  ' Module            Startup
  '
  ' Filename          tabstart.bas
  ' Module Prefix     St
  '
  ' Author            A. Developer
  '                   The Mandelbrot Set (Int'l) Ltd.
  '
  ' Description
  '
  ' Startup module for the table-driven FSM sample application
  '
  ' Revisions
  ' 11-12-97, A.Developer
  ' Added instance checking.
  '
  ' 08-12-97, A.Developer
  ' Moved global FSM object out of here.
  ' **************************************************************

The module prefix is a two-letter code used as a scope prefix that uniquely identifies this module in the project. Module prefixes are significant only for standard (BAS) modules.

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.
  '
  ' **************************************************************