Documentation

A key area with base code that is often overlooked is that of documentation. It's no good having a library of 20 code modules with hundreds of functions in them if developers have to search through all of them each time they want to see if a common routine already exists to do what they want.

Similarly, if the parameters and return values are not documented, developers might not be able to work out how to call a particular routine or how to interpret the results. When this is the case, the developers will invariably end up writing their own versions of the routine. Consider the following infrastructure routine's interface:

GetUserPrivilegeFlags(nUser As Long, _                       nPrivFlags() As Integer, _                       bForcePriv As Boolean, _                       Optional nForcePrivNo As Integer) 

I know that if I were not intimately familiar with this routine I would be tempted to write my own version. For example, is the array one-dimensional or multi-dimensional? Do I need to pass the array with values or an uninitialized array? How on earth are the last two parameters used? You can see the dilemma. The interface is of paramount consideration because it has the potential to scare off any potential users of the routine. Contrast the code above to the same fragment rewritten below:

GetUserPrivilegeFlags(ByVal lUserId As Long, _                       ByRef nPrivFlags() As Integer, _                       ByVal bGiveSpecificPrivilege As Boolean, _                       Optional ByVal nSpecificPrivId As PRIVILEGE) 

By using the ByVal and ByRef keywords, it is clear what is expected and what is returned. The argument names have been modified to be more meaningful, and the last parameter, nSpecificPrivId, has been typed so that a drop-down list of values will be displayed to the user, alleviating any ambiguity for this parameter's value. However, we still have the problem of not knowing the format of the exact requirement for nPrivFlags. This problem can be solved by using the Procedure Attributes item in the Tools menu. This allows you to enter a description that appears in the Object Browser when the procedure is selected.

The Object Browser

The Object Browser provides a fairly quick way to scan the contents of a code module. To assist with the scanning process, it is helpful to add a short description to the routines. To do this, select Procedure Attributes from the Tools menu. A description can then be entered that will appear at the bottom of the Object Browser window whenever the routine is selected. The drawback with this is that there is only a limited amount of space available here, and complex functions might require more information to be made available; however, it is possible to use the size bar in the Object Browser window to extend the viewable area. For the lazy ones among you, you can in fact enter procedure attributes directly in the code window. You do this by entering the attribute in the procedure—for example:

Attribute GetUserPrivilegeFlags.VB_Description = "My description" 

The line will be highlighted as a syntax error; however, if you save and reload the file, the Attribute line disappears and the description shows up in the Object Browser. Remember that the success of any base code template will be affected by the level of documentation.

Help Files

One approach that we use at TMS is to create a developer help file for the base code. This enables a structured view of the base code to be created. We generally create one help topic per code module, which contains the name and a brief description of each function within the module. Any function that requires more information can be linked to its own help topic, which can provide any detailed information to the developer. This approach has the benefit that keywords can be added to all of the topics, allowing for a search of the information by the developer.

HTML

Using HTML is a similar approach to using a help file, but this approach has the added benefit of being viewable over the company intranet. It also has the benefit of being maintained centrally; when the base code is changed, the developers will immediately have the updated documentation available.