0134 - Naming Conventions
Description:
A few suggested variable naming conventions and points to consider in creating a convention.
A few suggested variable naming conventions and points to consider in creating a convention.
Some sort of standard variable/dialog naming convention is a must. A good naming convention:
All will agree that a variable name should contain some type of indicator of the variable type. That is where agreement ends and opinion begins. Two great debates in particular are raging (well, maybe not raging ... ). 1) Should variable names omit spaces LikeThis or remain as separate words Like This, and 2) should the variable type indicator preceed or follow the variable name?
The contributions below highlight these schools of opinion and also demonstrate just how creative variable-naming conventions can be. Hopefully, they will inspire you in finding your own favorite approach.
WARNING: Capsoft has warned time and again against using ALL CAPS for variable or dialog names. ALL CAPS should be reserved exclusively for HotDocs instructions, models and keywords. If HotDocs should one day implement a keyword that you have used as a variable or dialog name, your templates will cease working.
• • • • • • •
First off, I have always run variable names together with the first letter of each name element capitalized LikeThis, partly because it is what I am used to with other programming languages, and partly because it makes computations much more readable.
As to a variable type indicator, for a long time I preceded the variable with a one- or two-letter indicator (t, n, d, tf, mc, c). That is the standard in almost all programming languages. But I have now abandoned that in favor of a trailing indicator. I find that it is very valuable to have similar variables grouped together in the variable lists, and leading indicators destroy this.
This is the scheme I currently follow:
Each variable will be followed by a "type indicator":
All variables that appear in templates begin with an upper-case letter. ClientFirstName-d, SigningDate-d, CorpSharesAuthorized-n, etc.
All "internal" variables begin with lower-case letters. An internal variable is one that is not saved to the answer file or that will never be inserted into a document. These tend to be programming and administrative variables. addName-c, getTransferee-c, nextCertificateNumber-n, etc.
The arguments for internal "functions" (see Computation #0117, How to make your computations mimic functions) will generally have the same name as the function. For example, addName-t is a text string that is passed to the computation addName-c.
Four generic variables (txt, num, dte, and tf) are used to pass values to function-type computations when there is no compelling reason to have a custom "argument" variable. For example, the computation Period-c determines if the preceding text lacks a period. The value that Period-c checks is the text variable txt. So the following line of code determines whether the variable TextVar needs a period: «TextVar»«SET txt TO TextVar»«Period-c»
All other three-character, lower-case variables are intended to be temporary, reusable variables for general use in computations. A few such variables might be int, pos, cnt, chr, and str. I do not expect the values in these variables to persist past the current computation.
Dialog names are in plain English, since the dialog name is the title of the dialog.
Beyond this, I agree with opinions expressed below about classifying variables by using group names. For example, the last name of the client would be called ClientNameLast-t, since the key group is Client, the secondary group Name, and the specific element is Last. Similarly, the middle name would be ClientNameMiddle-t. Thus all variables relating to the client's name are found grouped together in the variable lists.
Contributed by: LegalCS
• • • • • • •
I don't really think it matters what your naming convention is as long as it's simple and consistent. Both of these are extremely important.
First, it needs to be simple so that you can easily identify and remember the variable names that you have used in previous works so as to have matching variable names that allow you to use an answer file interchangeably between templates/forms, which is the main objective of HotDocs. Yes, you can always copy variables thru the component manager, but quite often, typing the variable name on the fly is much faster. If you've used abbreviations or have inconsistencies in your identifiers, you can easily mis-spell an existing variable name when creating it on the fly. Additionally, by incorporating spaces into your variable names it makes them easy to read, easy to understand what they are used for, and you can use uppercase or lowercase if you'd like. I do not use all uppercase for variable names because HotDocs instructions are all uppercase and if a new instruction comes out in the future with the same name as your variable you may encounter a problem.
Second, it needs to be consistent for all of the same reasons as stated above. I can easily look at a list of variables in a template and know by the MC designation at the end of the variable name that it is a multi choice variable. Same goes with DT for a date variable. If it's a 'd', I need to spend an extra moment or two thinking about the variable name that was assigned and then deciding whether or not it's a date variable for a dialog. It's just not efficient. Not only is it important that you are consistent with your code, but it's important that everyone that does HotDocs code for your firm uses the identical naming conventions. This will produce nothing but consistency and ease of use when assembling templates/forms in HotDocs.
Contributed by: Angela Hunt
• • • • • • •
First and foremost, I agree that consistency is key. Secondly, I try to keep my variable names short (so I can see them in that darned little box).
I, too, use extensions to identify the type of variable:
I have also found that naming dialogs in upper and lower case with "Information" on the end (e.g. Child Information) is a real help when inserting dialogs into each other. If you give your dialogs weird names then when inserting them you have to use the @PROMPT additional text to change what the user sees.
I try to name my variables in three parts:
So a variable would be child name txt.
I use lower case for all variable names.
I also try to use the subject for all variables that are together, such as:
child name txt
child birth date dt
child age co
Etc.
That way all my variables re child are together alphabetically for me.
Contributed by: Anonymous
• • • • • • •
Just to contrast, for those interested, I use somewhat more cryptic variable names with abbreviations. For example, the variables Toni referred to I would name:
ChNamet
ChBirthDated
ChAgec
I, too, use a subject first for grouping purposes, it's just that my subject is frequently abbreviated. For what it's worth, this has defeated its purpose from time to time. For example, if I wanted to name another set of variables for Charities, I would have trouble coming up with an abbreviation for Charity that did not cause those variables to be intermingled with the variables for Child in an alphabetical list. I might end up with the following variables (in alphabetical order):
ChAgec
CharAddresst
CharContactNamet
CharNamet
ChBirthDated
ChNamet
Admitedly, it would be easier to look at a list that was like this:
CharityAddresst
CharityContactNamet
CharityNamet
ChildAgec
ChildBirthDated
ChildNamet
I think I will stop abbreviating so much. But I still like the variable names without spaces. I think it is easier to read code when I am expecting a variable and I have one chunk of characters to look at or skip over.
Contributed by: Brian F. Albee
• • • • • • •
I use a slightly different approach. I attach the following "prefix" to the front of the variable, like:
I prefer a prefix to a suffix because it is more consistent with Visual Basic naming convention which is handy when we use the API kit to extract information from Access for preparing templates. So far, this has worked out well for me.
Contributed by: Anonymous
• • • • • • •
I program in BASIC, and am normally a fiend about prefix naming conventions. However, in HotDocs, since I have a separate component file for each template, I haven't really had a problem keeping track of variable types. These are the only naming conventions I follow:
Fields from the same source group are named with the same prefix: DefLast, DefAttyAddr, ClientLast, ClientFirst, and so forth.
Commonly used fields are recorded in a single component file, "A Prototype.CMP", which is used to copy common names and computations into each template. This keeps me from having PlFirst in one template and PlFirstName in another, and PlBirthdate in one and PlBirthDate in another. This is important for templates to feed from one to another through answer files.
Single word names, such as DefAttyFaxPhone, are used for fields from the database and for simple fields shared between templates. Pl Mailing Address is a computational variable stringing together address lines and city/state/zip.
Dialogs are named with a multiple word name ending in "Dialog".
The goal of these conventions is to worry more about keeping the source of information documented, rather than worrying as much about the type of variable involved.
Contributed by: Pete Hoffman
• • • • • • •
A variable notation that is quite popular among Visual Basic and Access coders is sometimes referred to as the modified Hungarian notation. You would use a prefix for the variable that is lower case and is usually 2 or 3 letters followed by the variable name beginning with a Capital letter to distinguish it from the prefix. We use such a convention in both Access and HotDocs and find it works very well because it groups similar types of variables together in the HotDocs variable/component selection lists, and then within each variable type alphabetically. It makes it very easy to distinguish between types and to find variables quickly in the component/variable lists. It becomes especially useful when we link HotDocs answers to Access fields because the naming convention helps us to match types and avoid errors in HotDocs and provides backward traceability to fields in Access tables.
Here are our prefix conventions:
The convention of not using spaces or underscores is also a common one and makes your variable names quite readable with the first letter of each word in upper case.
Establishing a naming convention is extremely useful when another template author is reviewing someone else's template.
We have a longer list in Access, but the above list is what we use in HotDocs. You can also extend the naming convention to the names that you give to templates and clauses to help you distinguish them, by using prefixes such as tmp or cl. We distribute all our templates as RTF files so it is hard to distinguish between the main templates and the inserted clauses unless we use a naming convention.
Contributed by: Doug Simpson
• • • • • • •