Easy Naming Conventions
Version: FileMaker 15
Sunday, January 15, 2017
Just because you researched your project thoroughly, created an ERD and scrubbed it, doesn’t mean you are ready to start programming. The development process is much smoother when you have conventions to follow. Conventions make your databases easier to manage, especially six months down the line when you need to make changes.
Naming conventions cover files, tables, Scripts, fields, value lists, Custom Functions, table occurrences, variables, Let function declarations, Custom Menus, layouts, object names and anything else you can name in FileMaker. Some conventions are required by system software restrictions, others are organizational and some are even functional.
It is important to be consistent with your naming conventions throughout an entire project. You can change your naming conventions from project to project. I know I have when I discover new techniques.
Some conventions will be covered here right now but others can be gleaned by reading other blog entries here as well as sifting through the hundreds of downloadable files at databasepros.com and watching my videos at Thinkific. Obviously, your naming conventions should be set in stone before beginning a project but listing all my recommendations right now won’t have as much meaning out of context. No, it is much better to cover conventions in context in order to better understand why the convention is being used.
Naming conventions in the FileMaker market officially started in 2005 when a dozen or so well known developers got together and hashed out a white paper called the “FileMaker Developer Conventions”. This paper is still available on the internet from the filemaker.com web site but read it with a grain of salt. Think about the developers involved in the project. They all work for big firms with handfuls of people working on a single project. I doubt that describes most readers of this blog. Most people develop FileMaker solutions in seclusion for their company.
Naming conventions are designed to ease the development process. A group of developers needs far more stringent conventions to communicate the meaning of an object at a single glance to another developer. It’s almost like a language. A developer on a team should be able to look at the name of a field and easily determine the type, purpose and storage without really thinking.
In single person development projects, complex naming conventions can get in the way. Naming conventions are important, just not as rigorous as would be used in a group project. Let’s take an example of a primary field in a contact manager. The white paper suggests to name a primary key field in the following manner:
The underscore at the beginning sorts the field to the top of the list so it is easy to locate when creating relationships. The “kp” at the beginning identifies it as a primary key and sorts it along with foreign keys which should contain “kf”. The “lt” identifies the field as a locally stored text field. Underscores are also used instead of spaces for web compatibility. The second word identifies the table it represents in case the field is observed out of context. No reason is given for the last word “id” but I suspect it identifies the primary key as a serial number used for structural relationships as opposed to primary keys used for techniques such as a concatenated key.
For the most part, everything makes sense to me except the “lt” portion. It sounds like a good idea but in practice it clutters the field name. Names should be concise but meaningful. If the convention is not useful, get rid of it. Each person is unique and finds different naming conventions useful but for me personally I don’t find knowing the field type or storage useful simply because my structural keys are always text fields. I prefer a simpler approach. Therefore, I name my primary keys with the following convention:
Again, it’s really up to you what naming conventions you use. I’m just trying to keep you from getting caught up in what is considered proper conventions and overcomplicating your development process. In my approach, less is often more.
Here’s an analogy I think enhances my point of view. If someone throws ten balls at you at the same time, you can probably catch a couple. Why throw more text at a name than is necessary. It just makes the name harder to read. Think about what you are doing and include only meaningful text in your names. Yes, read the naming conventions white paper but with skepticism. Adjust it to meet your own unique needs and style.
Some conventions cannot be avoided. Take for example naming conventions for file names. There are just some characters or combination of characters that can’t be used because they are restricted by the system software or FileMaker. For example, most system software has limitations on name length. It has increased over the years but there is a limit. You also have to consider how other systems such as ODBC could react errantly to a file name. Even FileMaker has restrictions. If you put a period in the name of your file in addition to the one separating the file name and the extension, the Get(FileName) function will not work properly.
Other file naming conventions are just common sense. Don’t put versioning in your file names since it can cause problems with file references in multi-user solutions. Using concise names also allows you to better see the entire name in a dialog such as Manage Database, Specify Field, Open Remote and the Script Workspace to name a few. And, don’t forget cross-platform differences in dialog sizes! The full name of an object may be visible on the Macintosh but not on Windows.
To end this blog entry, here is an example of naming conventions gone awry! The first thing you should notice are the variations in case and separation. Both upper, lower and title case are used extensively, providing no consistency. Separators are inconsistent with spaces, underscores and even tilde characters acting as word separators. It’s enough to scramble your brains!
Also, notice that the file contains the word "recovered". Yikes! I have so much to say about that but let's stay on track!
More subtle points include unusually long field names such that the name cannot be completely displayed with the default column size. Names should always be clear but concise. Every field begins with “Acq” so the ability to locate a field using type ahead has been completely removed. Always consider naming conventions that enhance FileMaker features.
My naming conventions tend to be short and simple. The only fields I begin with an acronym are key fields and global fields. Other than that, my field names are all lowercase with underscores as separators. Since fields are heavily referenced by third party products such as ODBC, SQL and web browsers, I like to keep the names compliant.
I like to start all global fields with an “x” so globals all sort to one area of the field list. Lots of developers use “g” or “z” or even “zz”. I just started out with “x” so I have stuck with it. Whatever you find works, use it. Also, it’s a good idea to place global fields in their own table since relationships aren’t needed to reference them from anywhere in the file. If the global field is to be used as part of a filtered relationship then include it in the parent table where the filter is utilized.
Layouts are also heavily referenced during web deployment so use strict naming convention. I try to avoid scripts in web deployed databases since I find they are just a crutch for poor design. In other words, most every conceivable functionality can be achieved using the FileMaker PHP API with supplement from standard PHP functions.
I tend to use uppercase and lowercase when naming tables, scripts, value lists and a variety of other FileMaker objects simply because they are not referenced by external products. This allows for a more full featured name such as shown in the following script name:
Go to Layout [Invoices]
The square brackets differentiate the function from the object that function is acting upon. I can type in “layout” and quickly filter all my layout type scripts or “invoices” and see all my invoice related scripts. At a glance, the brackets offset the function from the object, making it easier to read.
For Let variable declarations, I use the at sign (@). I know a lot of developers use dollar signs ($) but I find this causes confusion that a script variable is being declared (which can be done in a calculation formula). Other developers use a tilde but I find this difficult to identify in the middle of the rest of the formula. The at sign stands out like no other character in my opinion.
More of my naming conventions will be discussed throughout this blog as needed. I just want to instill the idea of simplicity at this point. I’ve seen some horrendous databases in my time that are so hard to follow because the naming conventions are either inconsistent or too hard to read. Make your naming conventions just complex enough to accomplish their task which is quick recognition of the important definitions of that object according to the way you develop your solutions.
John Mark Osborne
This blog is completely free. Please support it by clicking on one of the advertisers at the left side of the window or becoming a patron. Thanks so much!