Naming Conventions in FileMaker
Implementing reliable naming conventions in FileMaker has the potential to save developers both time and frustration. This is the second installation in our blog series on code readability.
According to Wikipedia, a naming convention is “a set of coding rules for choosing software identifiers (names of program elements) in source code and documentation. The reasons for using a naming convention […] are as follows:
- To make the source code easier to read and understand with less effort;
- To improve the appearance of the source code (for example, by avoiding long names or abbreviations)”
However, naming conventions can be controversial. Everyone has their own style when it comes to naming fields, variables, scripts, objects, and even documentation. Additionally, there is no standard way to name parts of code.
We recommend having teams of developers agree upon a set of clear naming conventions in order to establish expectations. Naming conventions should be logical and follow the principles below to the fullest extent possible.
Ideally, the chosen naming convention can be applied not only in FileMaker, but also other languages, because FileMaker can be integrated with other systems or modules, such as those created in JavaScript. Proper naming conventions are simple and can be applied everywhere; they also tend to be the most intuitive.
Basic Principles of Naming Conventions
- Be consistent
Try to find a standard way to name things, being as consistent as possible with word choice. Try to use the same words to say the same things.
For example, we’ll use a “lower camelCase” nomenclature and the underscore to separate words or groups of words.
2. Avoid abbreviations & acronyms
The meanings of abbreviations and acronyms aren’t always apparent. At worst, other developers may need to run Google searches to try to understand the meanings of unclear abbreviations and acronyms. It is also difficult to remember these meanings and look them up in code.
On the other hand, some abbreviations and acronyms are part of the IT/Computer/Coding common language and are sometimes better known than the non-abbreviated version. For example, “id” for “identification”, “MB” for “megabyte”, “GUI” for “Graphic User Interface”, “API” for “Application programming interface”, and others such as “SQL”, “HTML”, “REST”, “CMS”, “ERP”, etc. These abbreviations and acronyms may be acceptable. The real goal is to avoid non-standard abbreviations and acronyms.
It may seem counterproductive to use longer names, especially since today’s development environments all offer auto-completion features and text expander programs. Comprehension is often better using full names.
However, having names that are too long can also be an issue. Some development environments, such as FileMaker, can truncate these names, making them difficult to read. The ultimate goal is to find a happy medium, prioritizing understandable code over shortened names.
3. Be meaningful
Avoid arbitrary series and words that can create confusion. It is important to keep solution context in mind when naming things. For example, a completely arbitrary variable name that has no connection to the solution is not desirable.
One possible exception to this rule is that the variables i and j are often used for loop counts. We recommend adding meaning to your code by mentioning what type of count it is, such as userList_loopCount, or by mentioning it in a comment.
4. Avoid data type encoding
This may sound like a useful practice, but for better flexibility/extensibility, this ambiguity may be awkward and difficult to maintain. The name should be a higher level of abstraction from the implementation details of the actual field or variable type.
One possible exception: In FileMaker, when we add a gl_ or g_ prefix or suffix to a field name, for example gUsername. In these cases, it is not the data type that is specified, but the scope/visibility of the field, much like the $ and $$ in a variable name.
5. Use a generic & professional vocabulary
Some projects change developer teams several times during their lifetime; others are cross-cultural. The name you choose in your code will be read by a variety of people, and can be interpreted differently by different people.
The naming convention should be generic and as professional as possible, and should not include expressions in a common language. It should also not be offensive or too cute.
6. Be positive
It is easier to understand what is expressed positively. For example, “I’m happy” is easier to understand than a phrase with a similar sentiment, “I am not unhappy.” Try to name positively by using prefixes like “is”, “has”, “can”.
7. Avoid spelling mistakes
This rule should apply everywhere in our communications with others, not just in our code. Spelling mistakes and grammatical errors can make our code harder to read. This highlights the importance of proofreading code.
We hope that this article has been informative and is something you can immediately apply to your development practices. Check out the video below for a tongue-in-cheek guide as to why proper naming conventions are critically important.
FileMaker Best Practices: Guarantee Lifetime Employment with the Magic of Naming
*This article was originally written for AppWorks, which has since joined Direct Impact Solutions. This article is intended for informative purposes only. To the best of our knowledge, this information is accurate as of the date of publication.