Naming Conventions

In any project, establishing and adhering to consistent naming conventions is crucial. These conventions serve as a guide for developers and users alike, ensuring that everyone understands what a particular piece of code or data represents without needing to delve into its underlying details.

Benefits of consistent naming conventions:

• Enhanced Readability: When names follow a predictable pattern, it becomes easier for anyone reviewing the code to understand it quickly.

• Improved Maintainability: Consistent naming aids in maintaining the project as it evolves over time. It simplifies tasks such as updating features or fixing bugs.

• Facilitated Collaboration: A shared naming convention allows team members to work together more effectively since they can anticipate how objects are named and organized.

• Easier Onboarding: New team members can get up to speed faster when there's a clear and logical naming system in place.

When you add an object (device, model, variable, etc.) it's necessary to fill in the Name field. It is recommended to use lowerCamelCase style with no spaces within a multi-word name, starting with a lowercase letter and then capitalizing the first letter of each subsequent word. Do not include spaces between words. For example:

• Context name: monitoringMainPage, mqttDevice

• Function name: getUserInformation, xmlHttpRequest

• Variable name: inputData, unitsList

There is no need to mention the context type in its name and description. The type is clear from the container/group the context is located int. It also appears as part of the context path.

Therefore, use names like “highTemperature” and descriptions like “High Temperature” instead of “highTemperatureAlert” and “High Temperature Alert”.

Always fill in the Description and Comment fields wherever available (in device, model, variable, etc). Concise descriptions allow engineers to quickly understand the purpose of any object, which is very helpful during application development and maintenance.  

Comments to rule sets help engineers to understand both the purpose of individual steps and also the overall structure of the function.

Comments should reflect the essence of an action rather than describe each operation used (e.g. why this operation is used and not another). Such an approach helps achieve the following:

• Comments are not overloaded with excessive details

• Through comments you can understand the purpose of different steps without reading their code

• If a part of rule set function needs revision, comments will help to quickly find the necessary step, without reviewing every step individually.

In expression code, comments should be minimized. Well-written expressions normally require no comments. Properly written code implies using understandable object names and splitting complex expressions into several steps or functions.

Here are some Description and Comment examples:

• Suppose we have a function, that shows information about a user, selected by input parameters. We can call it "getUserInformation" and give information in the function description like "Get information about the specified user"

• Information in a rule set comment lets you understand the step purpose without reading the code. In the example of a rule set that checks the validity of a message with its signing key, there could be comments each step like “Retrieve the public key of the sender”, “Separate the message signature from the message“, “Check message signature with key and message” and so on.

To enhance the portability and re-usability of your code across various contexts, it is advisable to use generic terms instead of trademarks or other personalized names. This practice ensures that your code remains flexible and adaptable, avoiding potential legal issues associated with proprietary terms.

When developing an application, it's crucial that every name accurately reflects the essence of what it represents. This practice is not just about adhering to a development standard; it's about creating an application that is intuitive to maintain. Objects within an application are frequently referenced throughout the development process. For instance, when you need to retrieve or manipulate data stored in variables, having meaningful names allows you to quickly identify the correct variable among many.

Moreover, using understandable names in expression code will significantly eases the processes of fine-tuning applications and debugging when issues arise.

When naming contexts within your application that are designed for specific actions or pages, include details about their purpose in their names. This approach makes them self-explanatory and enhances readability.

Good Practice:

• monitoringMainPage - Clearly indicates this context relates to the main page of “Monitoring| section

• monitoringSettingsPage - Specifies this context is associated with settings of the monitoring process

Poor Practice:

• monitoring - This name is too vague and does not provide information on what aspect of monitoring it pertains to

For functions that carry out similar but distinct actions based on different parameters or conditions differentiate them clearly by their names. Doing so helps developers understand what each function does without needing to delve into its implementation details.

Good Practice:

• findUserByNameOrEmail() - Indicates this function searches for users by either name or email.

• findUserById() - Clearly states this function looks up users specifically by their ID.

Poor Practice:

• findUser() - Does not convey any information about how this search operates.

For effective application testing, it is recommended to utilize distinct objects (device, model, variable, etc.) that have been specifically created for this purpose. To facilitate easy identification and subsequent cleanup of these test artifacts at the end of the development process, it is advisable to append a special prefix or postfix—like "test"—to their descriptions. An examples is provided below.

Imagine you have a rule set that retrieves a data table containing device telemetry. This data is crucial for subsequent steps within the rule set. However, if the device becomes temporarily inaccessible and operational tests cannot be performed as planned, you can adopt an alternative approach of using:

• Duplicate the step within your rule set.

• Add a comment with "test" to indicate that this step uses test data.

• Replace the source expression with a predefined format table containing your test data.

• Set the condition in the original step to false.

This method allows you to continue testing your rule set operations while ensuring that all steps using test data are clearly marked for easy removal later on.

An alternative solution to the above scenario is as follows:

• Clone your entire rule set.

• Rename your original rule set by adding a "debugging" prefix.

• Append "for testing" to the description of your cloned (test) rule set.

• In this new test version, substitute all resources that are currently inaccessible with constants or predefined test data.

Once debugging is complete:

• Locate and remove any rule sets labeled with "for testing."

• Revert back to using your original (prefixed with "debugging") rule set.

By following these practices during development and testing phases, developers can ensure clean separation between production code and temporary configurations intended solely for validation purposes.

Don’t forget to remove all resources used for testing. If you want to use them further, best practices are to create special context groups for test resources.

Functions and rule set within a model serve as the building blocks of an application, each executing a specific task. It's crucial that their names clearly convey their purpose, answering the question "What does this function/rule set do?" This clarity in naming facilitates understanding and usage throughout different parts of the application. Starting names with verbs not only provides immediate insight into the action they perform, but also aids in organizing them logically when sorted alphabetically.

Consider a scenario involving a device that establishes communication once daily. Within this model, there is a binding that invokes the getDeviceTelemetry function when a connection from the device is detected. The name of this function succinctly describes its role: to retrieve telemetry data upon recognizing an incoming connection from the device.

Additional examples illustrating effective function naming include:

• createSensor: Indicates the creation of a new sensor entity

• getUserInformation: Suggests retrieval of user-specific details

• sendAlertListByEmail: Clearly states that it sends out lists of alerts via email

Was this page helpful?

Tell us more

Send

Thank you!