Documentation

When all else fails, read the instructions.

Cahn's axiom

Documentation might be boring, but it's vital. The following (minimal) documentation set works well for Visual Basic applications:

Functional/Requirements Specification

The requirements should be written down, and this specification should reference a Visual Basic prototype rather than embed screen shots in the document. As a result, the document and the prototype together constitute the signed-off requirements. This combination provides a much more realistic representation of the requirements and leads to a solution that is much closer to what the users really want.

Design Specification

A concise design specification should be produced (and maintained). It should describe the key design points.

Excellently Commented Code

This form of documentation is key. In our experience, other forms of documentation invariably become out-of-date. How many times have you been asked to make a change to someone else's code? Do you trust the documentation, or do you review the comments and the code itself to find "the truth"? High-quality module and subroutine headers, excellent block and in-line comments, and good naming conventions are the best types of documentation possible. At TMS, we have tools that build "documentation" from the source files—it's a good test of the standard of commenting.

Test Plan

Testing within Visual Basic teams is generally too informal and ad hoc. Writing a test plan forces some advance thought and planning.