"No Holding Back FileMaker Blogging"
|
Navigation:
|
Support this site by clicking on a sponsor below or becoming a patron!
FileMaker 20 Video Tutorials
Become a patron of this FREE web site!
|
|
Recent Blogs:
|
Window Locking
 |
Everything Changes
 |
Subsummary Unique Count
 |
Scripted Change Log
 |
Abstracted Log
 |
|
Meta-Consulting
Meta-consulting is a service Database Pros offers to help other developers
over programming hurdles via GoToMeeting. Email John Mark Osborne or call John Mark at (909) 393-4664 to find out more about this service.
|
Tips & Tricks Videos
|
Quick Tip:
|
Open Script Disabled
If you have a multiple file solution, it is possible for open scripts, specified via File Options, to not run on opening of the file. This can happen when a file is opened hidden by a related field or via a Perform Script step. Only when the hidden file is selected from the Window menu and displayed will the open script perform. The reasoning behind this behavior is efficiency. If you have to wait for an open script to run just to see data in a related field, you will have unhappy users. Also, imagine if the open script shows a dialog and interrupts what the user is looking at on the original file. The only way to guarantee an open script runs is to use the Open script step or launch the file manually. |
|
|
Document Management Videos
|
Fun Stuff:
|
Hall of Fame
I started working with FileMaker 25 years ago and a lot has changed. Here are the folks I think need to be recognized for their effort in shaping the early FileMaker (in no particular order): |
|
|
Fireside FileMaker Podcast
|
RSS Feed
|
|
|
|
Naming Standards
|
Level: Intermediate
Version: FileMaker 18
Category: General
Tuesday, September 24, 2019 |
|
|
|
|
|
|
|
|
|
|
|
|
Just about every serious FileMaker developer has their own personal naming standards for fields, scripts, tables, layouts and anything else that can be named. There's really no correct naming standard. It's all about what works for you and your development style. Still, you need somewhere to start. I'm not just going to provide some specific ideas but the reasoning behind the choices I've made so you can better decide what works well for you.
Easy Naming Conventions
I wrote previously about Easy Naming Conventions. If you are a beginner, it might be best to start here to get a more straightforward discussion of naming conventions. It may be all you need at this point. Come back here if you want a more in-depth discussion of naming standards and hyperlinks galore.
The History
The first official naming standards for FileMaker were published by the mothership in 2005 with the help of a variety of seasoned FileMaker developers. I've preserved this document titled "FileMaker Developer Conventions" and have made it available for download at the end of this article because it's still valid today. Sure, a few things have changed in FileMaker but this is probably the single best resource for specific FileMaker naming conventions. This document includes all of the essentials including naming for files, tables, fields, table occurrences, layouts, custom functions, scripts, calculations, value lists and security.
While I don't agree with every naming convention, I do base a lot of my conventions on this white paper. For example, I use a version of their primary and foreign key naming conventions:
_kp_contacts_id
_kf_contacts_id
The document also suggests adding a "g" or "l" for globally stored or locally stored key fields but I just don't find it helps. Almost all of my primary keys are stored locally and when they aren't, I don't follow this naming convention. All I want sorted to the top of each table occurrence is the primary and foreign keys, which constitute ninety percent of my relationships. If you do decide to use the underscore to sort more fields to the top of your field list, the "k" will organize your stored primary keys based on serial numbers or UUID in one area so they are easy to find.
BTW: The "p" and "f" stand for primary and foreign but come after the "k" or key so they sort in the same area if more than the standard key fields have an underscore.
I like that this convention uses the table name in the field name to better identify the correct key fields whether they are primary or foreign. I can't tell you how many databases I've adopted that have named their key fields without the table name. It makes my life so difficult. The "id" at the end may not be necessary but for me it's just further recognition that this field contains key information that is not related to the data.
FYI: Take into consideration that the FileMaker, Inc. naming standards were written in 2005. A lot has changed since then. Some of the conventions are classic, others are outdated due to new features and other just won't fit your style.
Why?
Why is it so important to have naming standards for FileMaker objects? There are several reasons but I think the most important is digestibility. It's easier to pick up a solution six months later when you need to add on some features or fix a bug. If there's a consistent naming convention for your FileMaker objects, it makes relearning the solution so much easier. It's also a kind gesture if another developer has to take over your project. They may not use the same naming convention but if it's uniform throughout the entire solution, they can learn your language and start working with it quickly.
I'll discuss other reasons for naming conventions as they apply to the specific areas of FileMaker. Digestibility is just the common theme throughout the entire FileMaker program.
Before We Start
If you Google "FileMaker Naming Standards" or "FileMaker Naming Conventions", there's no lack of folks telling you how to name your fields, tables, scripts, etc. I've taken the liberty of wading through the mud for you and am presenting some of the most notable with links so you can be better informed. You'll see a lot of similarities and differences between these different sources so don't just adopt. Try to understand why each set of standards was set forth so you can choose which works best for you.- filemakerstandards.org
Matt Petrowsky of ISO FileMaker Magazine fame has taken the lead on naming standards for FileMaker since the original conventions were released by FileMaker, Inc. He updates his web site when necessary but at this writing, the last update was in 2013. That doesn't mean he isn't active, just there's no changes to the standards he's publishing. - Core Solutions Naming Standards
Core Solutions has published naming conventions since 1999, even predating FileMaker, Inc., in an effort to share the efficiencies they've realized over the years. Using a cohesive set of naming rules makes their systems recognizable by any of their developers, even in systems a decade old. Core Solutions also participated in creating the original FMI naming conventions mentioned at the beginning of this article. - DB Services Standards
The recommendations from DB Services are based on their internal naming conventions and standards based on years of experience and is the foundation of all of their solutions. What is really important, no matter what development naming convention and standards you choose, is consistency. - SQL Naming Conventions
What I love in this blog article is the focus on naming conventios for SQL or specifically the ExecuteSQL function in FileMaker. Skeleton Key asks why wouldn't a developer use naming conventions for fields and tables to promote the use of this incredible function. Kudos to Skeleton Key for exploring this small but important area of FileMaker naming conventions. - Naming Custom Themes
Here's another naming convention for a focused area in FileMaker. Themes often go unnoticed in the world of naming conventions but The Support Group has brought it to the forefront.
Again, just take the above resources, as well as the one you are reading right now, as recommendations. Develop your own standards and conventions with an understanding of why you are naming FileMaker objects the way you are. Don't just blindly follow what someone says. For example, most of the conventions listed above are written from the perspective of large companies where multiple developers are working on the same project. Most of the folks reading this article are independent developers. That doesn't mean what works for a group doesn't work for an individual. Just take what anyone says with an understanding of their perspective.
Fields
Ok, let's talk about naming conventions from my point of view. Probably the most important naming conventions apply to fields. Not only do you need to easily find a field inside of Manage Database, the Specify Field dialog and the calculation dialog but you also need to reference them from a variety of different platforms. But, let's not get too far ahead of ourselves and start with locating fields in the various FileMaker dialogs. In order to do that, you have to consider the methods by which you can locate fields.
Let's start with Manage Database. The only method you have for locating a field is using type ahead or sort. Sorting isn't very useful, allowing you to sort alphabetically by name, by field type, creation order and custom. Most of the time, my fields are in alphabetical order so I can use typeahead to quickly get to the field I want to modify. This means you need a naming convention that is succinct and begins with letters that will help you locate the field within two to three typed characters. Maybe you can type faster than me but my experience is three characters maximum for typeahead. In fact, typeahead is the only method for locating fields quickly in the Specify Field and Calculation dialogs.
NOTE: I sort Manage Database by creation order occasionally when I've forgotten the name of the field I created recently or want to place a bunch of new fields on a layout quickly. Switching Manage Database to sort by creation order changes all other dialogs that allow you to select a field, enabling me to find that field easily no matter which dialog I am navigating.
I prefer to stay on the keyboard whenever possible. I do like mousing around but the keyboard is very efficient when performing repetitive tasks. If you add preceding characters that identify things like field type, storage and other field settings (like some naming conventions recommend), type ahead essentially becomes useless. Even adding these values at the end of a field name seems overindulgent since you really don't need this information at your fingertips. Most of the time you just know the field type based on the name or can quickly find out by entering Manage Database.Keep it Simple Stupid!
The one preceding character I put up with is the letter "x", which identifies and groups global fields for me. Some people like to use a "g". Others like a "z". I don't typically have a lot of global fields so I'm not worried about them gumming up my table and therefore don't usually have a globals table. Sometimes I do and since global are, well, global, they need no relationship to be accessed anywhere in the current file. The preceding characters not only organizes my globals but differentiates them from their regular field counterparts. Yes, that's right, global fields often act as an interface to a regular field, at least in my development practice.
Another important naming consideration is meaningfulness. If your field names are long, you're going to be scrolling a lot more looking through a sea of characters. Why deluge the brain with more information than is necessary to get the job done. Make it as easy as possible to identify a field. Not too short and not too long. Just right. For example, name your fields like so:
name_first
name_last
name_middle
name_full
Starting these fields with "name" sorts them all to the same location in an alphabetical listing. Since they are often used together, this makes it easy to find them. And, there's no need to put a "c" on the "name_full" calculation field, either at the beginning or end. Relational rules dictate the first and last name shouldn't be stored in the same so it's obvious the field is a calculation field. No need to complicate the succinctness of the field name and make it less meaningful.
Crazy but true... I've seen dozens of databases with all the fields in each table preceded with the table name. It fails naming convention practicality in so many ways including readability, typeahead and visibility. The typeahead thing is easy to understand but what do I mean about readability and visibility. If your field names are too long, it makes your calculations and merge fields longer, making them harder to read. It even makes your standard fields less readable in layout mode since the names don't fit into the borders of the fields, requiring you to double-click on a field just to see the table and field name in it's entirety.
I didn't forget about visibility but I felt I needed to start a new paragraph. If your field names are too long, they won't be visible in the default column size of Manage Database and other dialogs. Some dialogs don't even resize so you'll never see the full name of the field. I can't tell you how many times I've been developing on Windows and cursed the tiny little popup menus that display table occurrences that I have to guess which I want. I know this isn't a field but it's the Specify Field dialog and I got a little PTSD flashback. Out of my system so I feel better now.
So, what's the conclusion? Keep your field names as short as possible but meaningful. Use names that work well within the organization rules of the dialog like typeahead and sorting. This will make your development life much easier when working with field dialogs.
If you've been paying attention, I mentioned platforms in the opening paragraph of this section as well as the previous paragraph. Most people aren't just developing solutions for a single platform. In terms of fields, you don't need to worry too much about the differences between Windows, OSX and iOS. You can pretty much do anything you want and FileMaker will warn you when creating the field if there's an issue with the name. Just don't make names too long. What I want to talk about is the world wide web. Not WebDirect but custom web publishing using XML, PHP or the FileMaker RESTful APIs. Since the field names are often referenced in a URL, you'll need to make sure there are no spaces or uppercase.
If you do use spaces, they will be encoded as a "%20", making the URL harder to read. That's right, it won't stop your web solution from working but I can tell you I often have to troubleshoot by deciphering a FileMaker generated URL. All those "%20" values just muddy the waters. As for uppercase, the web doesn't really care when it comes to domains but does distinguish between upper and lower case after the domain. I just like to stick with lower case so everything is standard and my name value pair URLs aren't yelling at people. Therefore, I've adopted an all lower case with underscores for my field names.
Again, I'm not really providing any specific naming conventions for fields. Yes, I've provided some examples but only to illustrate my points. What I want to teach you is to think for yourself. If I teach you how to fish, you are much better off than me just giving you the fish. If you understand what's important for naming fields, you can come up with your own naming strategy. This will lead to a better understanding of FileMaker and ultimately a happier development career.
Tables and Table Occurrences
Table names are almost as import as field names. Tables are also referenced in a variety of different places such as merge fields on layouts, popup menus listing table occurrences and the relationship graph. Quickly identifying a table or table occurrence is key to efficient programming. So, how can you name a field efficiently? I like to go with single name tables whenever possible. I also type my tables in all caps.
CONTACTS
INVOICES
PRODUCTS
CUSTOMERS
Then, I like to name each table occurrence starting with the table name in all caps followed by the functionality. It allows me to quickly identify the source table for my table occurrences. Since I use the anchor-buoy system for relational design, I usually end up using the anchors table name in proper case. Using the example above, I've rearranged and renamed it to be a graph representing a relationship grouping based on invoices as the anchor. I've also added quite a few additional occurrences so you can see how I do things.
NOTE: If you want to read more about the anchor-buoy relationship system, read an article I wrote called Wrangling Relationships.
A lot of developers name their table occurrences starting with the name of the table being connected. It ends up being the reverse of my methodology. Either way seems to work well to organize the popup menu in the Specify Field dialog, and other dialogs, so you can see like table occurrences together. But, I like all my table occurrences grouped according to table and not connected table. Just seems to make sense to me. It's all up to you. Maybe you adopt one of these methods. Maybe you create your own. Even if you go down the wrong path, you've learned something. You can always change your naming convention on the next project to better suit your development style.
There's another reason I name my table occurrences starting with the table name and that's because I have a similar naming convention for my layouts. All layouts start with the source table, followed by their functionality. This enables me to grab the table name using the Get(LayoutName) or Get(LayoutTableName) along with the LeftWords function to create adaptive scripts.
LeftWords(Get(LayoutName); 1)
For me, this naming convention is essential in my FileMaker development career. If you'd like to learn more, look at an article I wrote about this technique titled Ultimate Find. It talks about creating a find script but towards the end, it demonstrates how to make the script work with any table. One of the means to making the script adaptive is to choose the correct layout for displaying the found set no matter which table is being searched.
Scripts
Scripts aren't used on the web like fields so I like to be a little looser with my conventions. I'm talking about custom web publishing, not WebDirect, where almost every ability is controlled through PHP, XML or RESTful API calls. If you're using a lot of scripts then you aren't leveraging the API properly. If you do need to use a script, name it according to URL compliant naming conventions like lower case and underscores instead of spaces. Otherwise, you can use some of the more interesting characters to produce a more readable script name. When most solutions have hundreds of scripts, a concise and readable naming standard can really help you wade through the sea of scripts.
For me, it's all about separating object and action. For example, I might have a script that deletes a portal row using the principle of indirection so I would name my script like so:
Portal Row [Delete]
FYI: Indirection or dynamic or adaptive programming allows a script or calculation to adapt to a new table without modification.
The object is the portal row and the action is emphasized by placing the action is square brackets. Square brackets are easy to type (no need for a shift key) and really make the enclosed information stand out. I can also search by object or function easily. Filtering by "portal row" would give me:
Portal Row [Delete]
Portal Row [Add]
Portal [Sort by Last Name]
Filtering by "delete" would give me:
Record [Delete]
Portal Row [Delete]
Customer [Delete]
I've also been using this naming convention for decades. It's stood the test of time and I see no need to change. But, you don't need to copy me. Just follow a convention that works best for you. My point in showing you a specific example is to help you understand in what ways a convention can assist you in working with lots of scripts.
Let Variables
Some of your naming conventions are just how you started it out. Their a habit that's hard to break. For example, I use an "x" at the beginning of all my global fields because that's how we did it at ISO Productions back in the nineties. I saw no reason to change cause it's no better than a "z" or a "g" or whatever letter precedes your field name. All the letters group globals together. The same is true for Let variables. Here's an example from an article I wrote on Weight Lifting:Let(
[@Selection = Middle(
GetField(Get(ActiveFieldTableName) & "::" & Get(ActiveFieldName));
Get(ActiveSelectionStart);
Get(ActiveSelectionSize));
@Size = TextSize(@Selection; MYTABLE::xsize);
@Color = TextColor(@Size; RGB(COLORS::red; COLORS::green; COLORS::blue));
@Result = TextStyleAdd(@Color; Evaluate(Substitute(MYTABLE::xstyle; "ΒΆ"; "+")))];
@Result
) You can see how much Let variables simplify this formula. You'll have to read the article to understand the formula but my point is that a good naming convention really helps with more complicated formulas. I like to use the at sign (@) but the basic principle for adopting a naming convention should be the same:- Should be concise
- Allow the variables to be easily identified within the result formula
- Allow reserved words to be used as variable name
I started using the at sign (@) when Kieren Macmillan shared some formulas with me soon after the Let function was released. He's not in the FileMaker market anymore but his naming convention adheres brilliantly to the rules set forth above. It's only a single character so it's simple. The at sign (@) isn't used anyhwere else in a calculation formula so it really stands out in the code with it's unique rounded look. It also allows you to use reserved words like function names since every variables starts with the at sign (@).
Other standards suggest using tilde (~) but I'm not a big fan. It just doesn't stand out enough IMHO. I've even seen developers recommend using dollar signs for variables but this is just plain wrong. The only time you should use a single or double dollar sign in a Let variable is when you are trying to declare a script variable. Otherwise, it's just simply confusing. Someone will come along, read your code and think there is some reason you are declaring a script variable.
Value Lists
Value Lists can't be filtered like scripts or layouts but they can be searched in the Database Design Report (DDR). Therefore, it's a good idea to name them concisely. I usually just apply standard proper case and spaces. Do take note that Value Lists can be sorted so try to follow a convention that allows you locate lists based on alphabetical organization. Other than that, I don't concern myself with Value Lists too much. I do try to include information about where they are used like when a value list is designed for find mode only or is defined as a conditional list based on a relationship. In the case of value lists for find mode, it allows me to name the version for browse mode and find mode the same so they sort to the same area:
Customers
Customers [Find]
Again, I use the brackets in this case to make the function stand out. In the example of conditional value lists, I might name a value list like this:
Products [by Type]
It's a very simple naming convention but keeps me from clicking through the endless array of overlapping dialogs to get to the definition. Anymore complicated of a name and it stops providing me the information I really want at a glance.
Layouts
I've already covered layout naming in the table section but let me emphasize the importance of layout names. I use them for indirection and not just to identify the table and function of the layout. Sure, the table attached to a layout and the purpose of a layout are extremely important pieces of information to have but not writing a bunch of scripts to navigate between each form and list view is just as important to me. It unclutters the Script Workspace and makes it easier to update a script since the code is centralized.
Custom Functions
Naming conventions for Custom Functions are pretty easy. Just follow the guidelines set forth by Claris. Those guidelines are the same as Claris adheres to for their functions. Try to stick with one word but when necessary, use upper camel case. For parameters, Claris switches to standard camel case. Why change the calculation format. Just go with the flow and make everything consistent. Your Custom Functions are listed right along with the existing functions so there's no need to change it up.
Security
I often use account names to connect the currently logged on user to their record in a table. This allows me to get information about them without using an ersatz security system. Only real security can provide a guaranteed connection to data stored in a table based on accounts. This might be information like an email address or contact information. Therefore, I make it easy on myself and always use a person's full name when creating their account. Some people complain but they get over it quickly. It makes my life so much easier.
In terms of privilege sets and extended privileges, I create so few of them, the name doesn't really matter that much. I usually end up with "Data Entry" or "Marketing" or "Sales". Extend privileges are always a single word and describes the basic grouping functionality. If you aren't familiar with creating your own extended privileges, the basic idea is to extend the business logic of a script or calculation. Instead of testing for each privilege set in an If script step, simply test for the extended privilege that groups the various privilege sets together. When you need to update how the scripts works in terms of security, all you need to do is update the extended privilege.
Files
In the old days, developers used to name files beginning with an underscore to hide them on the network. I also remember naming files with the eight-dot-three convention (wow, I'm old) to adhere to DOS naming conventions that ran deep through the structural code of early versions of Windows. Ah, those were the days! No need for that foolishness anymore. Just name your files for cross-platform compatibility with all operating systems including Windows, OSX, iOS and Android. While Android isn't really a player when it comes to files for FileMaker, I would include just in case FileMaker Go is released for Android. And, don't forget that file names are used in custom web publishing URLs.
Object Naming
I'm not enamored with the object naming feature. It's really annoying that FileMaker duplicates the name and places "Copy" at the end. It defeats the whole idea of naming objects since I duplicate almost every object but don't name every object. Then you look at a DDR or the Layout Object palette and you can't search it properly due to so many objects with the same name. FileMaker needs to fix this issue for naming standards to be effective for layout objects.
When FileMaker fixes this issue, I will name objects more diligently. The scheme I like to follow is including the object type in the name. This stems from so many objects needing to be named with the similarly. For example, I might have a notes portal, a notes field and a notes tab panel. Therefore, I name my objects like this:
Notes Field
Notes Portal
Notes Tab
If I didn't do this then I would have naming conflicts. Plus, it helps me identify the object type more easily.
What Should You Do?
There's a lot of conventions out there to follow. Don't just adopt one cause someone says so. Think about the architecture in FileMaker and how the named feature gets used. Consider how FileMaker interfaces with that feature and how a good name can enhance that experience and make you more efficient in your programming. Really, all I'm telling you to do is think about what you are doing and how it will affect your style of programming. Don't just adopt a convention blindly since we are all unique individuals with unique clients.
Author:
John Mark Osborne
jmo@filemakerpros.com
www.databasepros.com
Example File (available to patrons at $5.00 per month): Download here if you are a patron
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!
|
|
