Commenting Your Procedures

In general, you should add a new comment when you declare a new and important variable, or if you wish to make clear some implementation method. Ideally, procedures should only have one purpose, and they should be named clearly enough so that excessive comments are not needed.

In addition, procedures should begin with a comment describing what the procedure does, and that comment should be broken up into various sections. The Microsoft recommendations for those sections appears in Table 3.1.

Table 3.1: Procedure starting comment block sections.
Section heading	Comment description
Purpose	What the procedure does.
Assumptions	List of each external variable, control, open file, or other element that is not obvious.
Effects	List of each affected external variable, control, or file and the effect it has (only if this is not obvious).
Inputs	Each argument that may not be obvious. Arguments are on a separate line with inline comments.
Returns	Explanation of the values returned by functions.

Here's an example, showing how to set up a comment preceding a function named dblSquare():

'*****************************************************
' dblSquare()
' Purpose: Squares a number
' Inputs: sngSquareMe, the value to be squared
' Returns: The input value squared
'*****************************************************
Function dblSquare() (sngSquareMe As Integer) As Double
    dblSquare = sngSquareMe * sngSquareMe    'Use *, not ^2, for speed
End Function

*Related solution:*	*Found on page:*
Commenting Your Code	93