Clearly written code is easy to maintain and support. Readability improves when using self-explaining names and proper indentation. It is advised to keep all names and descriptions in a commonly used language within the organization so that relevant audience can understand what is being accomplished. This topic covers items to aid in clarity.
Suggested Practices
These guidelines are suggestions to aid in writing clear business rules.
Business Rules Objects
When naming business rules in the system, the following limitations should be implemented:
- ID: Title case, no spaces or special characters
- Name: Title case, spaces allowed
Description Field
As with most objects in the system, every business rule has a description field. Creating a short but detailed description of what the business rule is expected to do and in which context it is used will aid future users and set expectations.
Bind Variables
Bind variables should be named in camel case and starting with a letter. These binds should be named so that the name of the bind variable clearly identifies which bind is being used.
Use bind instead of hard coding IDs
When creating business rules, a bind allows for supporting a myriad of inbound data rather than a specific hardcoded ID. This is the preferred approach when a business rule does not need context-specific bind, which renders the business rule untestable using the standard business rule test functionality.
For business rules that potentially have context specific binds, such as current workflow, it can, however, be a better approach to retrieve the workflow using the manager and a hardcoded workflow ID. This method will allow the business rule to still be testable.
Variable and Function Names
Variable and function names should be in camel case and start with a letter. Underscore characters may be used.
Although the Rhino engine used for executing JavaScript is reinitialized prior to the execution of each JavaScript plugin script fragment, it is considered recommended practice to declare all script variables using the 'var' keyword.
Error Messages
When defining error messages for business rules, always make sure that one of the messages is in English to make them easier to understand for a broader audience. Note that the use of the '{size}' variable allows the error message to have more meaningful contextual use.
Code Layout
Business rules code lines should be 80 characters or fewer. To clearly structure the nested code values, indentations with the tab button are recommended.
function toCelsius(fahrenheit) {
return (5 / 9) * (fahrenheit - 32);
}
for (i = 0; i < 5; i++) {
sum += i;
}
if (time < 20) {
greeting = "Good day";
} else {
greeting = "Good evening";
}
General Housekeeping
It is recommended to clearly mark unused business rules as being obsolete, such as by adding a 'NotUsed' prefix to the name, if they cannot be deleted. It is equally advised to mark temporary business rules with a prefix like 'Temp.'
