A Few Programming Disciplines
updated 10/16/02

The following Visual Basic programming guidelines should be followed. They are listed in no particular order.

  1. Name all controls, forms, etc. before writing any code.
     
  2. Do not use Global variables. If you use variables global in a form or class, make sure they are private. Globals lead to problems with coupling.
     
  3. Do not use DIM to declare class level variables, use only Private or Public, Public only rarely.
     
  4. Naming variables: Start with lowercase, use uppercase for extra words in the variable name (or use '_' between words). Example: maxWidgets, max_widgets.
     
  5. Declare only a single variable in each declaration.
     
  6. Always use Option Explicit. This will require all variables to be declared.
     
  7. Always use Option Strict. This will require explicit type conversions.
     
  8. Don't use text boxes in calculations or as the target of a calculation. Copy the values out of text boxes into variables, copy a single variable value into a text box.
     
  9. Don't do math operations in a output statement. Store the value of the operation into a variable and output the variable.
     
  10. Break your program up into reasonably sized modules (forms, classes, .bas modules). Break your modules up into reasonably sized subs and functions. See #12 about cohesion.
     
  11. Name your methods using the same rules as variables. (See #4)
     
  12. Modules and methods should do one thing well. This is called cohesion.
     
  13. If a method returns a single value (or object) use a function.
     
  14. To communicate between methods use parameters. Use ByVal to pass values in, use ByRef when values are passed back. Use ByRef carefully and sparingly. (The rule changes with increased use of classes.)ddddddddd
     
  15. Method bodies should have a maximum of 10 to 15 lines of code.
     
  16. Format code well. Indent the body of modules. Indent the body of control structures. Use single blank lines between logical sections of your code.
     
    ' This sub does something interesting
'
Private Sub foo(ByVal in As integer)
      Dim i As integer
      If i = in Then
    i = i * in
  Else
    i = i / in
  End If
      For i = 1 To in
    picture1.print i
  Next i
    End Sub
  17. Your program should have a brief comment in the main form that describes what the program does. The comment should include how the program does what it does.

    Each module should have a brief comment at the top of the module describing what it does and how.

    Each method should have a brief comment describing the method.

    If the methods are well written, the comment can be quite brief. If the method is not well written, rewrite it.
     
  18. If a variable is used only inside a method, declare it local to the method. (Some code incorrectly uses formal parameters to declare variables that are used in the method and never used by the caller.)
     
  19. When choosing an iteration structure: Use For when the number of iterations is known in advance. Otherwise: Use a DO/LOOP with a test at the bottom if the loop body must be executed at least once, use a test at the top if no executions are a possibility. (Choose While/Until by which reads best. Some folks use While at the top and Until at the bottom.)
     
  20. Never change the value of the For Loop control variable inside the loop's body. (If tempted use a DO/LOOP.)
     
  21. When choosing between IF/ELSE and Select/Case, use the structure that provides the most clarity and simplicity to your code.
     
  22. Always include a Case Else in your Select structures. Use the Case Else for error checking, always have a Case for every option your program may support.
     
  23. When using Boolean variables in your program don't compare them to True/False in IF or DO structures. (Using good variable names will help avoid this.)
     
  24. Never use magic numbers in your program. Always declare constants. Use an "As Type" in your constant declarations. (Const MAX As Integer = 100) Use all uppercase for your constant names: MAX_WIDGETS.
     
  25. If you ever feel the need to violate the rules above, justify it in your comments.