Process Automation: Three Things to Consider When Naming HotDocs Components

You have purchased a HotDocs Developer license, reviewed the tutorials, and perhaps even received some development training. You may have gone so far as to have read topics of interest in the HotDocs help file, or perused the HotDocs Wiki. At any rate, you’re ready to start developing HotDocs process applications for your law practice or business.

Your training and reading have taught you that the core functionality of HotDocs revolves around the components, or variables, you create. (A component is anything you create in the component file that is associated with your document template [e.g., dialogs, variables, etc.].) And so it may have occurred to you that the naming conventions you use for your components are critical to the long-term functionality and serviceability of your HotDocs Process apps. Here are three naming rules that will help you as you begin your HotDocs development.

Forbidden Characters and an Exiled CASE

Component names should be relatively short, yet meaningful. A component name can have up to 50 characters, including letters, numbers, and some symbols. However, the first character must be a letter. Each component name must be unique—even if the components are different types, their names cannot be identical.

The following characters may be used only if there is a character other than a space immediately before or after it; however, use of these characters is strongly discouraged, considering possible future changes to HotDocs:

You cannot use the following characters when naming your components:

Finally, because HotDocs uses UPPERCASE for its instruction and expression models, it is best practice NOT to use uppercase at all when naming your components. You cannot, for example, name a component “ADD ATTY TO MC,” because “ADD” is a reserved instruction word in HotDocs. Even if you use uppercase for words in your component names that are not currently instruction or expression models, you never know for sure whether or not HotDocs will add the word you made uppercase to its list of reserved words. So it’s better “CamelCase,” “Sentence case,” or “lowercase,” than “UPPERCASE” and sorry.

Genus > Species/General > Specific

A practice that helps organize components in the component manager as well as generally keeping like things with like is to name your components with words that start general, and then become more specific. For example, the root word in the component name could be a primary key word for a group or a subject (e.g., ClientName). This key word is often the first word of the component name but, depending on the component type, it may not be. Subsequent words in the variable name should be increasingly more specific, first describing a secondary group, if needed, and then more specific aspects (e.g., ClientRealPropertyLegalDescription). Generally, best practice is to avoid using articles and prepositions as much as is practical. If you have a choice between “NameOfClient” and “ClientName,” use the latter.

Examples

Waste Not 50 Characters, Want Not

Here is where I risk inciting a flame war. (For those unfamiliar with the term, a flame war ignites on Internet development forums when proponents of opposing and deeply held convictions about “their way” of coding disparage one another in a thread [e.g. Microsoft vs. Apple products].) What I suggest here may be impractical for those developers who have already automated many document templates using a different component naming convention, but for those just starting out, this may be worth considering: Use “CamelCase” or “Title_Case_With_Underscores” when naming your components, as I have done in the examples above.

Traditionally, many template developers have used Hungarian Notation to signify the component type (e.g., TE for Text), and many have kept whitespace (“spaces”) in component names for readability. The arguments for employing Hungarian notation have lost relevance since HotDocs 5, as newer versions of HotDocs have allowed template developers to view component types in the component manager as icons or text, and easily search and sort among them. As for whitespace, omitting spaces in component names gains the template developer that many more slots out of the allotted 50 to fill with meaningful characters that tell what a component does. In addition, using component names without spaces (e.g., “CamelCase”) is the default standard for the development of HotDocs Models (a topic worthy of a future blog post). Following this convention allows HotDocs to read the Model document and convert the “No Spaces” variable names into prompts in the interview without the errors you may encounter with the strict naming convention turned off.

A final thing to consider is that as HotDocs continues to evolve and align itself with other compatible technologies, the need may arise for requiring users to remove spaces from their component names. If this were to happen, HotDocs would provide a way to convert those components with spaces, but if you don’t use spaces in the first place, you’re that much farther ahead of the herd. In the end, HotDocs scripting is a programming language, and so the convention for naming components should be not only appropriate for HotDocs template development, but also in the same company with other programming or scripting languages.

Happy developing!