How To: FileMaker Naming Standards

RATING: Intermediate
PLATFORM: Windows & Mac
VERSION: FileMaker 4/5
TECHNIQUE FILES: None

Researching methods to the madness

In July of 1982 I was warming up on the tennis court with a friend named Dennis Unkovic. As we were getting ready to start our match, he asked me, "Have you ever heard of muscle memory?" I said, "Yes. Why?" He said, "Well, I have amnesia."

I think that Dennis was sandbagging me, because he played pretty well that day. But I have found that his zany comment can be applied to many situations in life, especially to many aspects of FileMaker Pro database development.

For purposes of this article, I have reviewed the following sources:

Barney Lawn's white paper entitled "FileMaker Pro Development Standards (11/17/2000), available at
< http://www.coresolutions.com >

MacAcademy/Windows Academy CD-ROM version of Barney Lawn's white paper bearing the same name
< http://www.macademy.com/ > or < http://www.windowsacademy.com/ >.

Matt Petrowsky's Scriptology Developer's Toolkit
< http://www.scriptology.com/ >.

Que Corporation's Using FileMaker Pro 5/Special Edition by Rich Coulombre and Jonathan Price
< http://www.quepublishing.com >.

E-mail exchanges with other developers.

My own experience in developing a system with 40+ files and 5,000+ fields.

Consistency is the key

I can now say unequivocally that incorporating consistent naming standards is one of the two most important things that I have learned about FileMaker Pro during the past three years. The other was the use of SetField to create new records in a related file, but that is the topic of another article.

Applying these standards consistently has allowed me to continue working on a project whose complexity was threatening to bring me to a standstill.

Why use naming standards? Because most of us suffer from "individual" amnesia, the inability to remember what you did, how you did it, why you did it this way and not that way, yesterday, last week, last month, last year, or 10 years ago.

Compounding this problem is the issue of "collective" amnesia, caused by a group of developers each suffering from individual amnesia, or worse yet, a developer staff and/or client staff that is not the same as it was one or more years ago (through promotions, attrition, layoffs, etc.).

There are two key components to the term "consistent naming standards":

The NAMES themselves. As you will read below, there are reasons to use some types of names and avoid other types of names. Some reasons are obvious, some not so obvious.

The CONSISTENCY with which you use these names. This is probably even more important than the names themselves.

But by incorporating standard names consistently, you will cut down considerably on database maintenance costs and allow other developers to step in more quickly to help you out (either in a pinch or for peer review/quality enhancement reasons).

When you apply such standards consistently, you can go back to any file at any time, even years later, and much more quickly pinpoint the area that needs your attention. These techniques take advantage of the human brain's ability to handle a small number of patterns better than a large number of patterns. Use of consistent naming standards essentially reduces the number of patterns to a small subset to which the brain can adjust with surprising speed.

What matters and what doesn't?

Where do naming standards come into play with FileMaker Pro? In the following areas, at the very least:

Fields [the subject of this article]
Files
Layouts
Relationships
Value Lists
Scripts

In Part One of this article (Field Names), I will describe what you can do immediately as the first step during Pass #1, then what you can do eventually in Pass #2. Pass #1 gives you the most "bank for the buck" and quickly shows you the benefits of this exercise.

Future issues will cover the other categories listed above. If you don't start your renaming project until after you receive all parts of this article, you might want to consider applying Pass #1 to all categories first, then Pass #2 to all categories at a later time.


Field Names: Suggestions & Methods

Several messages on the topic of naming standards complained about the ugliness of names such as "zvfieldnamegnr" ("v" for variable, "gn" for global number, "r" for repeating). A key element of standards is readability, and "zvfieldnamegnr" is not readable by most mortals. The addition of a simple underscore in several places and initial caps for all words except the first makes all the difference:

"zv_fieldName_gnr"

Pass #1

1) In Define Fields, sort by Type, so that the fields sort in the following order:

Text
Number
Date
Time
Calculation
Summary
Global

2) Remove spaces from the field names in the Text, Number, Date and Time types.

a) Add "_ae" at the end for "auto enter" fields.
b) Add "_r" at the end for repeating fields. You can eliminate the "_" if the "r" follows another sufix such as "_ae". Thus you would have "_aer".

3) Prefix all Calculation fields with "z_", and remove spaces.

One quick way to add the "z_" prefix is to add it once, then copy those two characters into your buffer (Ctrl-C/Win or Cmd-C/Mac), then paste the prefix into each successive field (Ctrl-V/Win or Cmd-V/Mac). Obviously you can also use this technique for the prefixes described in (4) and (5) below.

In addition, if using Windows when you change the field name, I find it faster to press Alt-A (for "Save") than to move the cursor over to the Save button on the lower right-hand side of the dialog box.

4) Prefix all Summary fields with "z_", remove spaces, and add "_s" at the end. For Calculation fields that use the "sum" function, you might want to add an "_sum" suffix to differentiate them from Summary fields with the "_s" suffix.

5) Prefix all Global fields with "zv_", remove spaces, and add "_g" at the end. After the "_g", you can add a "t" for text, "n" for number, "d" for date, "t" for time, and "c" for container. You can add an "r" at the very end for repeating fields.

Pass #2

6) Resort the fields, so that all fields starting with "z" sort to the bottom.

7) At the top of the list (those fields not starting with "z"), find all lookup fields and prefix them with "zl_". Even though these are not calculation fields, their values depend on values entered in other fields, and therefore are not pure "user-entry" fields.

8) Go down to your "z_" fields, and modify the prefix so that you create functional subgroups of calculation fields, such as:

zk_: "k" for "key". Add suffix "_pk" for "primary" (left side of relationship) and "_fk" for "foreign" (right side of relationship). Although the "k" in "_pk" and "_fk" might seem redundant, I find that having a "k" at the front and back of field names helps me identify key fields more quickly.

zlb_": "lb" for "label". Use for dynamic field labels.

zm_: "m" for "message". Use for dynamic messages to users.

zp_: "p" for "print". These are text fields formatted with check boxes that allow you to turn various pages on or off for printing purposes.

zf_: "f" for "fixed" values. I use these fields that are not calculated but contain data that a user should not change (tax tables, mortality tables, etc.).

zs_: "s" for "script". These are fields that are equivalent to calculation fields, except that their values are set by scripts. I sometimes move logic from calculation fields to scripts that set text or numeric fields in order to improve overall performance. Some values need to be set only when you move from one layout to another, or when you want to accomplish a specific goal within a layout via a button. By scripting these calculations, you cut down on sluggish recalculations and slow screen redraw.

zd_: "d" for "design". These are fields that use the various FileMaker Pro "design" functions (ValueListItems, ValueListNames, etc.).

Barney Lawn's white paper also suggests the use of of "zc_" (for "control") and "zi_" (for "interface"). I have had some difficulty figuring out when to assign "control" and when to assign "interface", so I prefer to make up my own categories that are more specific.

9) In the case of calculation fields where the field type could be ambiguous, consider adding a "_t" (for text), etc. This is particularly helpful when you might need to convert a true date field to a text version for concatenation with another text field or for parsing.

10) You might also consider adding a "_u" to calculation fields that are
intentionally or unavoidably unstored (because they depend on global or related fields). Early on in my FMP learning curve, I discovered that relationships that worked perfectly well (involving a foreign key consisting of a stored calculation field) suddenly stopped working.

This occurred when a field on which this calculation depended became unstored. This had a cascading effect, making unstored every other field that depended on this now-unstored field, and disabling every relationship that used it as a foreign key.

This problem can be very difficult to diagnose, so it is important to build in clues that allow for quicker diagnosis.

As a side note, one file was taking almost five minutes to recalculate every time that any value was changed. By converting all calculation fields to stored, we reduced the calculation time to about one second.

11) Rename fields like "Zip" to "customerZip" so that they don't fall in the "z" area. This is a good idea anyway, so that you group like fields together:

customerNameFirst
customerNameMiddle
customerNameLast
customerFirm
customerAddress1
customerAddress2
customerCity
customerState
customerZip

The above protocol, by the way, conforms to "Barney's Law" that you should assign names that start with the general, then move toward the specific. Thus, "customer" is most general, "Name" is more specific, and "First" is most specific.

Barney's CD-ROM also suggests starting each field with a lowercase letter, then starting each successive word with an uppercase letter (i.e., zc_createdTime). This improves readability.

Of course, from a purely relational point of view, you probably ought to have all of these customer fields in a separate Customer file, but the concept still applies. You could then move "Zip" away from the "z" fields by naming it "addressZip".

12) Add global text fields to serve as dividers, and name them as follows:

zv
zv -------------VARIABLES------------------------

Global fields apparently add almost no overhead to your files (this information is courtesy of Darren Terry and the excellent class that he co-taught with Fred Smith in Jerry Robin's Multi-User and Networking boot camps).

When you save such fields containing hyphens, you will see the following warning: "This name cannot be used in a calculation formula because it contains… Proceed anyway?" Just click on OK to proceed anyway.

After you create the first pair of fields, you can duplicate them one time for each additional divider that you need. Be sure to keep the name of the field with the hyphens short enough so that you don't get the annoying error message ("This name is too long") when the duplicate initially appends the word " Copy" to the end of the original name.

Note that you need a space after the "zv " in both cases. The space forces these dividers to sort above the fields starting with "zv_".

Define additional pairs of fields for the other categories:

zk
zk -------------KEYS-------------------------

zl
zl -------------LOOKUPS----------------------

zlb
zlb ------------LABELS-----------------------

zm
zm -------------MESSAGES---------------------

zp
zp -------------PRINT------------------------

zs
zs -------------SCRIPTED VALUES--------------

zf
zf -------------FIXED VALUES-----------------

zd
zd -------------DESIGN FUNCTIONS-------------

z
z ---------------CALCULATIONS----------------

This last pair of dividers will separate all of the fields that you have specifically subcategorized (with a character that follows the "z") from the fields that still start with just "z_". All the "z_" fields will appear at the bottom of the Define Fields dialog box.

It would be nice if a future version of FMP could provide a specific feature for separating groups of field names, as well as a mechanism for storing notes about what fields do.

Notes

1) An additional advantage to prefixing so many fields with a "z" is that the pure user-entry fields float to the top in the Define Fields dialog box. This allows you to focus more quickly on those fields for purposes of designing layouts, importing and exporting data, and matching fields with foreign files that you are converting to FileMaker Pro.

2) In layout mode, you can more quickly identify which fields are for user entry (coloring them white) and which fields are not for user entry (coloring them light gray).

3) There are several downsides to longer field names:

Some FileMaker Pro dialog boxes do not display more than 15 or so characters, and cannot be widened.

The column headers in Table View use exact field names and currently cannot be modified.

Merge fields on layouts can have names that are longer than the data itself, and can exceed the space available on the form. A workaround to this problem is to format the first "<" of the merge field reference to the size that you want for the data, then shrink the font for the rest of the merge field reference.

If you are using ODBC to incorporate FileMaker Pro data into Word or WordPerfect merge letters, for example, the field names will appear in Word or WordPerfect exactly as they do in FileMaker Pro.

For the relatively few fields that might be affected by the above issues, you could create calculation fields in FileMaker Pro with simpler names, and set them equal to the regular fields. These new fields with their simpler names can then be used in Table View and in ODBC connections.

4) Some data sources (such as.DBF) support uniqueness only to the first 10 characters of the field name. Keep this in mind if you think you will need to import or export such data. Thus, you might want to abbreviate the above customer fields as follows:

custNmF
custNmM
custNmL
custFirm
custAddr1
custAddr2
custCity
custState
custZip

5) You should not use the PERIOD character in field names (i.e., z.fieldname). Among other things, this will cause web browsers to interpret a web page improperly.

Credits

Although the following people did not review this article before publication, their publications, seminars or e-mail messages were important to its development:

Author of white paper and CD-ROM on the subject
Barney Lawn

Co-authors of Using FileMaker Pro 5/Special Edition
Rich Coulombre
Jonathan Price

Seminars
Jerry Robin
Fred Smith
Darren Terry

E-mail messages
Marcel De Maria
Ilyse Kazar
Heather McCue
Michael Power
Kurt Knippel
Beverly Voth
Dean Westover

ISO FileMaker Magazine
Matt Petrowsky, author of an important video on Naming Standards in his Developer's Toolkit, did review this article before publication.

Written by Vince Lackner (vince@lacknergroup.com).