Preparing an Application to Be Self-Documenting

Access ships with an excellent tool to assist with the process of documenting a database: the Documenter. Although you can use this tool without any special preparation on your part, a little bit of work as you build the components of a database can go a long way toward enhancing the value of the Documenter's output.

Documenting Tables

The Documenter prints all field and table descriptions that you enter in the design of a table. Figure 21.1 shows a table in Design view. Notice the descriptions for the ClientID and StateProvince fields. These descriptions provide additional information that is not readily obvious from looking at the field names. The Table Properties window also contains a Description property. The Documenter includes this property when you print a table's documentation.

Entering a table description also assists you and the users of your database work with the tables in the database. Figure 21.2 shows the Database window after table descriptions have been entered. The description of each table then appears in the Database window.

Documenting Queries

Just as you can enhance the output that the Documenter provides for tables, you can enhance the output the Documenter provides for queries. Figure 21.3 shows the Query Properties, in which the Description property has a detailed description of the purpose of the query. Figure 21.4 shows the description of an individual column in a query. Access includes both the query and field descriptions in the output provided by the Documenter.

Documenting Forms

Documentation is not limited to table and query objects. A form also has a Description property. You cannot access it from the Design view of the form, though. To view or modify the Description property of a form, follow these steps:

Documenting Reports

You document reports in exactly the same way you document forms. Reports have a Description property that you must enter in the Properties dialog box. Remember that to access this dialog box, you right-click the object in the Database window and choose Properties from the context menu.

Documenting Macros

You can document macros in significantly more detail than you can document forms and reports. You can document each individual line of a macro, as shown in Figure 21.7. Not only does this provide documentation in the Documenter, but also, macro comments become code comments when you convert a macro to a VBA module. In addition to documenting each line of a macro, you can add a description to the macro. As with forms and reports, to accomplish this, you right-click the macro in the Database window and choose Properties from the context menu.

Documenting Modules

I cannot emphasize enough how important it is to document modules with comments. Of course, you do not need to document every line of code. I document all areas of my code that I feel are not self-explanatory. Comments help me when I revisit the code to make modifications and enhancements. They also assist anyone who is responsible for maintaining my code. Finally, they provide the user with documentation about what the application is doing. Comments print with code modules, as shown later in this hour in the section "Using the Documenter." As with the other objects, you can right-click a module in the Database window and choose Properties from the context menu to assign a description to it.

Using Database Properties to Document an Overall Database

In addition to enabling you to assign descriptions to the objects in the database, Microsoft Access enables you to document the database as a whole. You do this by filling in the information included in the Database Properties window. To access a database's properties, you choose File | Database Properties or right-click the title bar of the Database window and choose Database Properties from the context menu. The Database Properties dialog box appears, as shown in Figure 21.8. As you can see, this dialog box has five tabs: General, Summary, Statistics, Contents, and Custom.

The tabs in the Database Properties dialog box do the following:

• General— The General tab displays general information about a database. This includes the date the database was created, when it was last modified, when it was last accessed, its location, its size, its MS-DOS name, and its file attributes. You cannot modify any of the information on the General tab.

• Summary— The Summary tab, shown in Figure 21.9, contains modifiable information that describes the database and what it does. This tab includes the database title, its subject, and comments about the database. It also includes the hyperlink base—a base address that is used for all relative hyperlinks inserted in the database. This can be an Internet address (URL) or a filename path (UNC).

  Figure 21.9. The Summary tab of the Database Properties window.

  

• Statistics— The Statistics tab contains statistics of the database, such as when it was created, last modified, and last accessed.

• Contents— The Contents tab, shown in Figure 21.10, includes a list of all the objects contained in the database.

  Figure 21.10. The Contents tab of the Database Properties window.

  

• Custom— The Custom tab enables you to define custom properties associated with the database. This is useful when you are dealing with a large organization with numerous databases and you want to be able to search for all the databases that contain certain properties.