I also focus heavily on embedded documentation in my tools, because it can be maintained and distributed along with the tools' design elements; because developers are much more likely to read it than a separate technical document; and because my own poor memory needs as much help as it can get--even during the initial development process. The hidden collapsed section titled "DESIGN DOCUMENTATION" contains the high-level information a developer needs in order to install and use the tool. More detailed documentation is provided for some individual fields via REM statements in their value formulas.

The design breakdown
In a reusable subform, formatting and other customizations should be pushed to the host form whenever possible. The Editor History subform intentionally doesn't include a title, collapsible section, or background color, in order that these may be customized to the host form without modifying the design of the subform. This is a huge priority when building a reusable tool, because all installations of a tool should be identical if at all possible. If you can successfully standardize your tools and maintain them from a single design template, you can distribute bug fixes and enhancements through simple design refreshes, instead of through tedious manual updates to each version.

In this tool, several customizations can be controlled by creating special interfacing fields on the host form. The simplest example of this is the line of additional instructions displayed at the bottom of the subform. By default, the fdEHDesc field computes to null and displays nothing, but if the host form has a field named fEHDesc, it will display that field's contents instead. Here is the formula:

DEFAULT fEHDesc := ""; fEHDesc

This is all very simple, thanks to the formula language's built-in DEFAULT keyword. The formulas that reference the other optional setting fields (fEHMax, fEHInterval, and fEHPrompt) generally use the same approach.

Now, let's look at the simple fields that compute during document creation and the initial save. The fdEHMax field is purely informational and works the same as fdEHDesc, so it requires no special attention. Next are the two fields in the "Created By" row, which store the name of the document's original creator and its creation date. They are fairly ordinary computed-when-composed fields that compute to the current user's name and the current time.

This is simple if we assume the Editor History subform will be included in every application from the very beginning, but what happens if the subform is added later and then used with pre-existing documents? For older documents, the fEHCreated and fEHCreator fields should use the original creator's name and creation date, not the current editor and time. So, these two fields' formulas are set to handle both new and old documents:

fEHCreator: val := @If( @IsNewDoc; @UserName; @If ( $UpdatedBy != ""; @Subset ($UpdatedBy; 1); "") ); @Name([CN]; val) fEHCreated: @If( @IsNewDoc; @Now; @Created )