Documentation Standards
Visual Basic Home Page

Use the following styles and standards in your Visual Basic programs. You may lose points on any assignment if you fail to adhere to these guidelines.

Coding

  1. Type blank spaces around operators of all kinds.

    Example: Instead of        intSum=intAmount+intSum
                     use                     intSum  =   intAmount  +  intSum
                    since it is much easier to read

  2. Use consistent indentation, especially with regard to complex structures like if statements, loops, etc. Do not indent the lines in the general declarations section of a form or code module. Indent all lines inside If/Then/Else, With/End With, For/Next, Do/Loop, Select Case, Type/End Type, etc. structures for readability.

  3. Line up inline comments where possible.

  4. Add blank lines above and below  structures such as loops and if statements. Also add a blank line below a section of code that contains variable declarations and below the remarks at the top of each procedure. Add a blank line between procedures.

  5. Make sure that you name each form and provide a caption to each form. The most important form in your project should be named frmMain.

  6. Follow the Windows standards, especially in relation to color, size, and placement of controls.  Also, use access keys that are considered standard in Windows software (e.g. x for Exit and s for Save). Do not give two controls the same access key.

  7. Make sure that the focus is on the correct object when a form displays. The tab order must proceed correctly when the user presses the Tab key.

  8. Constant & variable declaration statements should always appear at the top of a procedure. Constants & variables with module-level scope must be declared in the general declarations section of the form. Global variables & constants must be declared in a code module.

  9. Include the following information in the general declarations section of every form in a project and the standard code module:

    Programmer Name
    Project/Program Name
    Class Period
    Dates
    Program Description


    Help    		 ' John Doe
    ' Program #1
    ' Period 6
    ' 2/03/03 - 02/05/03
    ' Purpose - This program will calculate and display the number of days the user has been alive.
    ' Mark Schmidt helped with debugging                     

  10. If a procedure contains several major steps or functional parts, there should be comments (called signpost comments) separating the function into each major part.

  11. Never use goto statements.

  12. Statements which are continued on a second line must be indented further. You can use the line continuation operator ([space] _ ) to break up lines that would be cut off by the printer.

  13. Place parenthesis around control expressions in all If statements and loops. Even though this is not required in Visual Basic, it makes your code easier to read.

    Example:

    If (intSum > 100) Then
        lblOutput.Caption = "The sum is greater than 100."
    End If
  14. Use multiline If statements rather than single-line If statements to make your code more readable. Do not use If statements in the form,

    If (intSum > 100) Then lblOutput.Caption = "The sum is greater than 100."

  15. You must use the standard Visual Basic prefixes when naming objects (except for labels that never change throughout a program). Note that all object names are listed in the Form Text printout so scan that list to make sure that you have properly named all objects.

    Object Class Prefix Example
    Form frm frmUserEntry
    Command button cmd cmdExit
    Text box txt txtDescription
    Label lbl lblSum
    Option button opt optSingle
    Check box chk chkSummary
    Frame fra fraChoices
    Horizontal scroll bar hsb hsbSpeed
    		  
    Object Class Prefix Example
    Vertical scroll bar vsb vsbHeight
    Image img imgDesign
    Picture box pic picFace
    Combo box cbo cboList
    List box lst lstEntries
    Common Dialog dlg dlgCommon
    Menu mnu mnuFile
    Shape shp shpRectangle


  16. Use perfect spelling and grammar throughout your code, especially when it can be viewed by a user. If necessary, copy and paste your code into a word processor, like MS Word, and run a spell-check before you turn it in.

Documentation

  1. Use a consistent format with regard to internal documentation. If you use complete sentences in inline comments, then do so throughout your program's code, otherwise use explanatory, understandable phrases. Remember comments are the main form of internal documentation. They should be explanatory but not too verbose (wordy). They should help explain the purpose of the program or procedure in which they are used. They should also explain the purpose of variables within specific algorithms. Always use correct spelling, punctuation, and grammar within comments.

  2. Always include a variable dictionary to explain the purpose of each variable. That is, there should be an inline comment to the right of each variable declaration (Dim statement) and constant declaration (Const statement) that explains the purpose of the variable or constant. You can use phrases instead of complete sentences. Line up the inline comments vertically as much as possible.Variable declarations must be one per line and aligned consistently.

  3. Follow the InterCap method for naming variables (e.g. intTotalPrice), making sure that the proper prefix (in lowercase letters) is used to identify a variable's data type or a function's return type. Programs must be "self-documenting."   A program is self-documenting if its variable names imply the purposes of the variables. Variable names should be whole words or phrases that make refer to the purpose they serve within the program or function. Constants must be named with all-capital letters and underscores to separate consecutive words except for the data type prefix. For example, a module-level constant that identifies the maximum number might be named mintMAX_NUMBER.

  4. Annotate medium to complex algorithms and assignment statements with inline comments. Do not necessarily assume that fellow programmers (or instructors) will understand your logic. However, do not document the obvious.

  5. Every procedure and function should have a comment below the first line of the procedure that describes the purpose of the procedure. Place a blank line below this comment.