Let’s talk seriously, Remedy has one of the worsts code organization systems in the world. Also, BMC has not published any best practice guide for developing (apart of the best practice customization mode). So, any developing company must establish a set of best practices in order to ensure that its environment won’t result in a mesh of objects, and keep code organized.
In this post I will cover one of the most important parts of a best practice guide: The naming convention. I will start with the objectives of a good naming convention and provide an example of my own.
Main objectives of a naming convention for ARS
We can summarize the objectives in:
- Ease the search for code.
- Minimize the troubleshooting activities.
- Avoid the uncontrolled concurrent use of shared elements, like shared fields.
- Organize the code
To achieve this objectives the naming convention must ensure a set if constraints. If this constraints are accomplished, then the objectives will be achieved. These constrains include (but are not limited to):
- Identify the application associated with each object.
- Identify the parents of each object. That is, a workflow name must include a reference to the form it belongs. Or a filter that is part of a guide must include a reference to the guide.
- Use a clear brief description of the purpose of the object. Use a style guide for this description, so all objects are described in the same way. Incident, Incidents, Incidents Form and Incident Manager are four styles for the description.
- Don’t include any information susceptible to change, forcing the change of name in the future or loose of the name integrity. This includes the execution order or related temporally fields.
- Mark useful common characteristics in the name. These marks can include: Shared, call guide, View form, Web service interface, etc. Don’t mark characteristics susceptible to change in the future.
So, at the start of a new project, we must agree a naming convention between all stakeholders.
The execution order controversy
You can find on the Internet other naming convention guides. They normally tend to include the execution order in the name (BMC itself does). But I think that it is a bad practice. The execution order is visible in the Remedy Developer Studio when listing objects, so we can sort by this value easily. Also it appears on all the logs. And finally, it is very common that this value can change, when you want to reorder the execution of your code. A prove, there are a lot of BMC workflow objects with the execution order in the name that doesn’t match the actual execution order. Is that useful? Definitively not. It can only confuse when troubleshooting or customizing the application.
A naming convention guide for reference
As stated before, this is not the only good naming convention. There are a lot of possibilities that can achieve the stated objectives. The important thing is to have one and follow it.
Divisor
You need a character to separate each part of the name. Use the same as BMC uses, the colon “:”.
Marks
Use the next marks when applicable:
- *: Shared. Must be used in the place of the code that is referencing an element that can be multiple.
- _G: Guide Starter. In filters or active links to indicate that this workflow can trigger a guide.
- D_: Dialog form.
- I_: Interface form. A form that is created only to hold web services or elements created by workflow.
Applications
Aplication names must be short, with spaces and using capital letters for each word. For each application you must select an acronym or letter code(with a reduced lenght). Start the name of the application with the application code, and continue with the name. This will force you to select the application code when starting the application, and it will be easier for another developer to determine which application code corresponds to each application.
Some examples:
- PENC:Penalties Computation
- CPDMS:CPD Maintenance Scheduler
Forms of elements
A form of elements is a form that holds a list of elements, like a list of incidents, tickets, server or any other element. The form starts with the application code, and continues with the name of the element in plural and upper CamelCase. This can apply to regular, vendor or view forms.
For each form we must create a form code, that must be unique in the application.
Some examples:
- PENC:Penalties, with code P.
- PENC:EvaluationRules, with code ER.
- CPDMS:TimeFrames, with code TF.
Dialog forms
The dialog forms are named with the application code, the parent form code and the name of the dialog form in upper CamelCase. The name of the dialog forms is marked with “D_” and must explain the use of the dialog form. If the dialog form is created to be shared, must use the shared mark instead of the form code. The form code for a dialog form is the parent code followed by a unique code
Some examples:
- PENC:P:D_RelatedPenaltyFinder, with code P:RPF
- PENC:*:D_YesNoCancel, with code P:YNC
Interface forms
The dialog forms are named with the application code, the parent form code and the name of the dialog form in upper CamelCase. The name of the dialog forms is marked with “I_” and must explain which kind of interface it is designed for. If it is for Web services, must use WS.
Some examples:
- PENC:P:I_WS
- PENC:P:CreatePenalty
Guides
There are two major types of guides. The first is a set of activities to achieve one complex objective. The second is a set of related activities, like grouping all the state flow control filters in one guide. The first kind of guides must be named by the function they want to achieve. The second by the common factor of the elements, continued with the word “Set”.
The guide must start with the application code, and the form code. Also for each guide we must create a unique code.
Some examples:
- PENC:P:StateFlowSet, with code SFS
- PENC:*:UserNameFormat, with code UNF
- PENC:*:YNC:YesActionConstraintsCheckSet, with code YCC
Simple workflow elements
This applies to filters, active links and escalations. Must contain the function of the object, starting with the application and form name. Don’t include the execution order, or escalation periodicity.
Special cases:
- When the action is starting a guide, the name must be the name of the guide and “_G”
- When the filter is part of a guide, the name must include the guide code.
For instance:
- Normal Filter -> PENC:P:CheckSubmitterGroup
- Starting a Guide -> PENC:P:StateFlowSet_G
- Starting a Shared guide from particular form -> PENC:P:UserNameFormat_G (this is a not shared filter that starts a shared guide)
- In a Guide -> PENC:P:SFS:CheckFromActiveToInactive
Other objects
Name the object and start with the application code and form code. Avoid to mark the type of object in the name (for instance start all web services with WS).
