Variable Naming Guide

Ardexa sends data from your machine(s) to the cloud. More often that not, this data is accessed by many people outside of your company or agency. Some of the Ardexa plugins have fixed naming standards. For example, when we collect data from Wind Turbines, we ensure that the data collected retains the name of the variables provided by the original equipment manufacturer. Other plugins however, allow you (and in some cases require you) to define your own variable names. Those plugins that collect from Programmable Logic Controllers (PLCs) are an example.

This simple guide has been prepared for clients not familiar with variable naming. In our experience, variable naming is one area that causes serious problems, and can have very long lasting negative consequences.

If your data is likely to be accessed by your clients, partners, analysts and/or suppliers, it is critically important that you try and follow these rules wherever possible. Even if you think your data will not be accessed by anyone other than your own staff, the same rules still apply. If you do not maintain some level of consistency in variable names, you are going to encounter some very serious situations in the future, which are likely to be very, very difficult to fix. If you are not sure what to do when naming variables, then please talk to Ardexa before you do anything. We are here to help.

Basic Axioms

You need to keep in mind some foundations ideas when developing a method of naming your data. Here are some of the basic axioms of variable naming to remember.

Your clients may not have a clue about how your equipment is connected nor configured, yet will need access to the data

Your clients may not, and probably will not, speak your language, yet will need access to the data

Many different types of workers, partners, analysts and suppliers will need to get access to the data, and make sense of it

Variables and their units MUST (repeat MUST) remain consistent across implementations. This has caused serious headaches across many installations that have not followed this rule

Basic Rules

So with these basic axioms in mind, here are some rules you are very strongly encouraged to follow to avoid serious problems now and in the future.

  • Choose a variable naming standard and stick to it. Common standards include

    • Title case: "Turbo Power"

    • Camel case: "TurboPower"

    • Snake case: "turbo_power"

  • Do NOT use punctuation.

  • Keep the variable names short. For example, this is a bad variable name: "PowerToMyEngineWhenTurboisOn". This one is good: "turbo_power".

  • Choose a single language that will be most widely understood (and usable) by your intended audience. Can you understand "渦輪動力" or "Turboleistung"? If your market is Chinese or German, these may be good choices. Also consider character encoding support (we use UTF-8) when making your decision, some products may still only support ASCII.

  • Specify and use SI units wherever possible (see: https://en.wikipedia.org/wiki/International_System_of_Units). If this is not possible, then use the units you need to use, but remember, they MUST REMAIN CONSISTENT across all the machines and entities that specify the unit. If you cannot do this, then DO NOT use the same variable name for different units. You MUST use a different variable name if the variable uses different units. For example, if you have the variable name "comp_relay_in_p" to measure pressure in pounds per square inch, you MUST NOT use the same name for another machine to measure pressure in Pascals. You must use a different name, say something slightly different like "comp_relay_in_pa"

  • Try to encode some way of letting the client know the broader machine or entity that the variable applies. So for example; a name such as "eng_hyd_pump_p" would let someone easily know that this variable is likely to measure power output of the water pump attached to the engine. When following this sort of naming, the general rule is something like this:

{Entity A}_{Entity B}_{Entity C}_{what is it}_{what type of reading}

You don't need all 3 entities, you can have just 1. But if its a more complicated machine, you may need all three of them. Remember to keep the underscores separator between the entities, to keep it all lower case, and to keep it all short.

Some Examples

a. Say you have an outlet pump attached to a water reservoir. Here is a version of how you may name those variables:

  • res_out_pmp_v (for voltage)

  • res_out_pmp_p (for power)

  • res_out_pmp_fl (for flow rate)

b. Say you have frequency controller attached to a battery. Here is a version of how you may name those variables:

  • batt_grid_freq_v (for voltage)

  • batt_grid_freq_fin (for freq in)

  • batt_grid_freq_fout (for freq out)

  • batt_grid_freq_a (for current)

c. Say you build compressors which use a relay to control the release of incoming water pressure. Here is a version of how you may name those variables:

  • comp_relay_in_v (for voltage)

  • comp_relay_in_p (for pressure)

  • comp_relay_in_on (boolean on/off)