Visual Basic —

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