The following table lists suggested conventions for objects you might encounter while programming VBScript.
Code Commenting Conventions
All process should begin with a brief comment defining what they do. This description must not defined the implementation details (how it does it) since these frequently change over time, resulting in needless comment maintenance work, or worse, erroneous comments. The code itself and any necessary inline comments specified the implementation.
Arguments passed to a process should be described while their reason is not obvious and while the process expects the arguments to be in a particular range. Return values for variables and functions that are modified through a procedure, especially through reference arguments, must also be defined at the starting of each procedure.
Procedure header comments have to include the following section headings. For instance, see the given table which described the section heading & the comment contents to be inserted whilst developing code.
|
Section Heading
|
Comment Contents
|
|
Purpose
|
What the process does (not how).
|
|
Assumptions
|
List of any external control, variable or other element which state affects this process.
|
|
Effects
|
List of the process's effect on each of external variable, control, or other element.
|
|
Inputs
|
Clarification of each argument which is not obvious. Each argument must be on a separate line with inline comments.
|
|
Return Values
|
Clarification of the value returned.
|