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