The Impact of Naming Conventions on Code Readability

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

  1. 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.

Example of a naming convention with inconsistent names

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.

Example of a naming convention with acronyms

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.

Example of a naming convention with non-meaningful names

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.

Example of a naming convention with data type encoding

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.

Example of an unprofessional naming convention

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”.

Example with a naming convention with a double negative

 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.

Example of a naming convention with a spelling error

We hope that this article has been informative and is something you can immediately apply to your development practices. We would love to hear other best practices for creating naming conventions in the comments. 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