In-Line Documentation

One of the best sources of documentation is the code itself. When you follow a specific coding format and thoroughly comment your code, you're making your program more readable and providing valuable information to yourself and to other programmers who might have to make modifications to the code later.

Formatting

Follow these rules when formatting your code:

• Punctuate your code with blank lines.

• Keep your procedures to a manageable size—preferably not much more than a single screen.

• Keep indentation under control. If you're having difficulty remaining within the right margin, you're probably nesting too deeply.

• Use parentheses to enhance the readability of your code. No one reading your code should have to wonder what you meant when you wrote it.

• Preserve screen real estate wherever possible. For example, when creating a long string, it might be better to build up the string with multiple assignments:

   Dim sMsg As String sMsg = "This is a paragraph that is to appear " sMsg = sMsg & "in a message box. The text is " sMsg = sMsg & "broken into several lines of code " sMsg = sMsg & "in the source code, making it easier " sMsg = sMsg & "for the programmer to read and debug. " MsgBox sMsg, vbOkOnly, "Text" Dim sQRY As String sQRY = "SELECT Customer.CustomerName, Orders.OrderValue " sQRY = sQRY & "FROM Customer, Orders " sQRY = sQRY & "WHERE Customer.CustomerId = Orders.CustomerId" ReportQry1.SQL = sQRY 

Code Commenting

The comments in and around the code and, to a lesser though highly important extent, the names and identifiers used within the code, constitute the readable English in a program. Both individually and as a collective comments animate the code to the reader and help explain what is happening.

Comments typically center upon some sequence point, around which some current "code-wise" activity focuses. In other words, comments explain what has happened or is about to happen in the code. Comments must always therefore provide a narrative or biography of the code—past and present. Additionally, comments are not contained within the "built" Visual Basic code and as such have no overhead attached to them. Don't be afraid to comment code in the belief that it will cause code bloat and the like.

The important rules for commenting are as follows:

• Keep comments up to date and directed towards being excessively verbose, if anything.

• A good comment is a high quality comment. Quality, not quantity, is all important.

• Use capital letters to issue warnings and signal important announcements.

• Comments must be clear and concise—always attempt to add value and never simply restate the obvious.

• Use short comments to say what is happening and longer comments to say how and why the state transition is occurring.

• To reduce the number of comments you use, try to write code that does not require commenting.

• By using clear sentences and parallel structure in comments, you avoid ambiguities and any resulting confusion as to your intent.

End-of-line comments

End-of-line comments should be used to annotate variable or constant definitions:

 Const MAX_ROWS As Long = 2147483647 ' (2^31)-1 (Max value for                                     ' long integer) Const ICONIZED As Integer = 7   ' To startup applications                                 ' with Shell(). 

In-line comments

End-of-line comments are rarely suitable for annotating code. Where a function or subroutine contains a number of logical blocks, introduce each block with a separate comment indented to the same level as the code. Use as many lines as necessary, and don't use surrounding ***** lines to delimit comments unless something really important is about to happen. Keep comment lines short so that the entire comment can be viewed on a VGA display without scrolling left and right.

Use comments to explain the code, not to echo it; if your comments become very involved, consider restructuring the code. Complicated explanations can also be moved into the function header. The following code shows some examples of appropriate in-line comments:

 MaxCol = nColumn - 1 XL_NewRow stDataBlock XL_NewRow stDummyRow ' The dummy row now holds the long form of the column headings. ' Appending this to the main data block gives us both long and ' short headings, one below the other. XL_AppendBlock stDataBlock, stDummyRow ' We now need to step through the data array and extract the ' records for each row in turn. Records corresponding to a ' single row all have the same code and description and are ' contiguous in the array (which is sorted on description). ' The row description array returned by GetNextRow is sorted ' on column number. nDataIdx = 0 Do While nDataIdx < nNumRecs 

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