Naming Convention Best Practices

Introduction

This document provides basic advice on logical, scalable naming conventions for apps and other Mendix elements. While everyone can benefit from employing these conventions, they have added benefit for organizations who are making apps and components at scale.

Modules

Module Names

Modules should be treated like standalone replaceable services; for example, the customer module should function as a standalone customer management system as much as possible, replaceable by a different customer management system. Module names should have UpperCamelCase names that identify the responsibility of the module, for example, CustomerManagement or SharePointIntegration.

Module Roles

The module roles should have logical names that reflect the access they should have within a module. In contrast to the user role, the module role should always be in English, for instance Administrator or Employee.

Domain Model

Entity Names

Most of the time, an entity reflects a real-world object that people can relate to. Therefore, the entity name should also reflect that object and identify its purpose. There are sometimes app-specific exceptions that lead to creating other types of entity, but that is up to you. The name of an entity is singular since an object is a single instance of the entity. A good example is using Customer and not Customers. Furthermore, we advise avoiding abbreviations, underscores, mathematical characters or any other special characters in the names of entities. Entity names also use UpperCamelCase, for example, HousekeepingRecord or LogEntry.

Entity Attributes

The entity attribute should reflect a property of a real-world object that people can relate to and fits the purpose of that property. We advise avoiding abbreviations, underscores (except in the case described in the next paragraph), mathematical characters or any other special characters in the names. Entity attributes should use UpperCamelCase, for example, FirstName or TelephoneNumber.

Attributes that do not reflect business-related data, but are only necessary for technical reasons, should start with an underscore (_).

Associations

Naming Multiple Associations Between Entities

Association names in the domain model are automatically generated by Mendix. The auto-generated names follow the best practice and should be used by default.

If you have multiple associations between the same entities, Mendix recommends extending the association name. Extending this name with a recognizable purpose clarifies where you should use the association. For example, you can have a relationship between Person and Address. A person can have multiple addresses but you want to specify what their postal address is and what their delivery address is. An implementation choice could be that you create two associations for that purpose and adjust the names of the associations accordingly. For example, Person_Address_Delivery.

Renaming Entities

When an association already exists between entities and you change the name on one or both of the entities, Mendix will rename the association automatically.

With models built in lower versions of Mendix, however, you will need to manually rename the association to keep your model consistent and up-to-date.

Folders

Folder Names

Mendix recommends to use unique folder names that clearly identify their contents. You can use any combination of letters and symbols to identify a folder. For example, when adding a Published OData Service to your app, you could name the folder holding the service ODataAPIs or OData_APIs to reflect its function.

Keep in mind that folders do not affect the full path of the resource. For example, when referencing the folder ODataAPIs in MyFirstModule, the path name would be MyFirstModule.ODataAPIs.

Folder Structure

The structure for your documents starts with a clear separation of folders. By using a good folder structure you will improve the maintainability of your application; you will be able to find required documents faster and therefore will be able to develop and fix faster.

The optimal grouping of your documents into folders depends on the circumstances and on the functionality of your application. Mendix recommends combining the guidelines below in a way that fits your app.

Process-Related Sources

Every app consists of processes. Structure your documents for these processes into folders that reflect individual processes and their steps.

Entity-Related Sources

Every app has documents that are needed for specific entities. Think of overview pages for maintenance, validation microflows that prevent commits, or other event triggers. These types of document should be structured into one folder that is named after the entity. Optionally, sub-folders could be used to organize, for example, events and pages.

Microflows

Generally, microflow names should include the type of event which triggers them, the name of the main entity being processed, and the operation being performed: {PREFIX}_{Entity}_{Operation}. For example, ACT_Vendor_StartWorkflow.

There are exceptions, such as where there is no main entity, or there is another reason to use a different name to improve understandability. The important thing is to make sure the name of the microflow clearly indicates its purpose.

To easily find and recognize the purpose of a microflow, you can use standard prefixes. Common purposes or events and their standard prefixes are listed below. If a microflow is triggered by several events, consider using more than one prefix. If a microflow does not comply to any of the patterns listed below, it should not have a prefix.

Entity Event Microflows

For some entities you use entity events that are always triggered when a specific operation is executed on the entity.

For example, an attribute TotalOrderAmount is automatically filled based on the amount values of the order-related order lines. You can define an after-commit event that ensures that TotalOrderAmount is updated when a related order line is saved: ACO_Order_CalculateTotalOrderAmount.

The microflows related to such an event handler should have the following prefixes:

Calculated Attribute Microflows

For attributes, you can choose to store the value in the database or to calculate the value based on a microflow. For the microflow that does the calculation, you should use CAL_ as a prefix and refer to the entity and attribute which is being calculated. The calculation is triggered when you show the entity on a page or use it in a microflow. On a page, the object's calculation attribute refreshes if you navigate away from the object and back to it in any way (via pagination buttons or tabs or by re-entering the page).

Page-Based Microflows

Pages have a number of events that can trigger a microflow. See the following list for the examples and prefixes:

Workflow Microflows

You can call a microflow from a workflow. See the list of examples and prefixes in the table below:

Validation Microflows

Microflows that are used for data validation use the prefix VAL_.

Scheduled Event Microflows

For the microflow that you use in your scheduled events, use the prefix SCE_. The event itself should have a descriptive name since it will be shown in the cloud configuration portal. The scheduled event and the microflow should have the same name.

App Microflows

Your app settings provide three events that can trigger a microflow. In these cases we advise writing out the purpose as a microflow name. These microflows are defined only once per app and should preferably call sub-microflows to do the actual processing. These sub-microflows should have a prefix indicated below:

Sub-Microflows

To clearly identify a sub-microflow, use the prefix SUB_. Exceptions can happen if there are other sub-microflow prefixes that are generally accepted too, for instance, the sub-microflow prefixes mentioned in the App Microflows section above.

Unit Test Microflows

Microflows containing unit tests should have the prefix TEST_ or UT_ (case-insensitive). For more information about the Unit Testing module, see Unit Testing.

Integration Microflows

For integrations, you have the following types of microflow:

You can also use the Find Advanced option in Studio Pro to search for microflows by service type.

Workflows

Guidelines below can help you choose a short yet meaningful name for your workflow:

• The name matches the context entity name
• The name consists of a noun + verb (for example, EmployeeOnboarding)
• The name reflects what the process is about, what the goal of the process is

Other Document Types

Layouts and Snippets

Layouts and snippets should be identified with prefixes.

Enumerations

Enumerations should be identified with a prefix. The name of the enumeration should reflect its business context, for example, ENUM_ShippingStatus.

Pages

Pages use a suffix to indicate their use.

Pages that show an overview of a single entity should have a suffix of _Overview.

Pages that are to create, edit, or view entity data, and that are not part of a process, should have the suffix _New, _Edit, _NewEdit, or _View.

Pages that are used to make a selection of one object have a suffix of _Select where the multi-object selection pages should have the suffix _MultiSelect.

Pages that are used as a tooltip page should have the suffix _Tooltip.

Pages that are called when a user task in a workflow is executed, have suffix _Workflow. There is one task page per user task. These pages always have a WorkflowUserTask data view and are specific to performing workflow tasks.

Integration Documents

Documents used to support integration should have the prefixes listed below.

Home Pages

You can define the home pages per device and role in your navigation. The recommended page names are listed below: