The other day, I was teaching a lab for recently hired at MathWorks. In that lab, I ask attendees to program LEGO MINDSTORMS robots using Simulink. One of the things I see in this lab is that people often struggle asking questions like:

• What are the units of this signal? Radians or Degrees?
• What is the meaning of that 0.15 value I put there
• What is that signal? A velocity or a position?

The answer to that is a good naming convention.

To describe the important things to consider when defining a naming convention, I am happy to welcome guest blogger Michael Burke. Being part of the MathWorks Consulting Services team, Michael has worked with multiple customers on multiple projects and has seen tons of different naming conventions.

What’s in a Naming Convention?

Naming conventions are a method for providing information about variables in your model and generated code. Done well they are easy to understand and work with. However we have all run into projects using Elder Gods naming conventions — unpronounceable, indecipherable and impossible to remember.

So what makes for a good naming convention? Like flavors of ice cream this is somewhat to taste, but like good ice cream there are known good ingredients. In the case of naming conventions, information is the good ingredient.

Ingredients

Who:

• Explanation: With the “who” you are telling what the variable is used for; it should quickly let a user/reader know if this is something he needs to review.
• Examples: HorseSpeed, HorseSp (using abbreviations)
• Ice cream equivalent: This is the most important part, this is the high fat cream.

What (Units):

• Explanation: Working with physical units (kg, m, watts) or software constructs (flags, counters, states), units explain the role your data plays.
• Examples: HorseSpeedFurlongsPerFortnight, HorseSpFpf
• Ice cream equivalent: Salt, you forget that it’s in there but it makes everything so much better.

Where (do I come from):

• Explanation: The “where” part of the data tells where the data is written to or originally defined. This can aid in the partitioning of the data.
• Examples: HorseSpeedRaceTrackFurlongsPerFortnight, HorseSpFpfRacet
• Ice cream equivalent: Makes debugging easier so it is like sugar, sweet.

Role:

• Explanation: The role defines the data as a signal, constant or tunable parameter.
• Examples: ConstHorseSpeedRaceTrackFurlongsPerFortnight, conHorseSpFpfRacet
• Ice cream equivalent: Your base flavor such as chocolate or vanilla

Data type:

• Explanation: It is not uncommon for people to include the data type (e.g. double, uint8) in the name of a variable. With the exception of logical variables, this is generally a poor design decision and should be avoided as it limits the portability of the code.
• Examples: DoubleConstHorseSpeedRaceTrackFurlongsPerFortnight, DbConHorseSpFpfRacet
• Ice cream equivalent: Jimmies, sure some 6 year old likes them, but not for long.

Storage class:

• Explanation: Like data type above, including information about storage class limits the long-time portability of the data.
• Examples: LocalDoubleConstHorseSpeedRaceTrackFurlongsPerFortnight, LocDbConHorseSpFpfRacet
• Ice cream equivalent: Month-old diced peanuts sprinkled on top.

At this stage you are no doubt looking at these names with recognition of the Elder God problem mentioned above. An engineer who had been with the company for 15 years would know all the abbreviations and could decipher the meaning but for the rest of us it is a gibbering chant. The good news is that there are guidelines on how to avoid this problem.

Mixing it up

When creating a naming convention there are 2 primary guidelines.

Make it human readable: Human readability is achieved through 3 things:

1. Delimitation - either using CamelCase or under_scores.
2. Consistency - always have the same type of information in the same portion of the variable. (e.g. don’t have HorseSpeedMPH and MPH_DonkeySpeed.)
3. Limit information - as tempting as it is to place as much information as you can into a variable, generally 2 or 3 bits of information are all it takes before it becomes overwhelming.

Brevity is the soul of naming conventions: Abbreviations for naming conventions, especially for units, is key to usability:

1. Use standard abbreviations where possible (e.g. MPH is known to be miles per hour)
2. Try to use between 2 and 4 characters for the abbreviation
3. If you can’t, consider using underscores to delineate

Consider these examples of a battery current variable where “I” is the common abbreviation for current:

• BatteryI: It is easy to miss the “I” character at the end due to the short length
• Battery_I: I now sticks out due to the “_” characters
• BatterCur: You could also use the abbreviation “Cur” for current.

Now it's your turn

I hope the stars are in alignment for you and that you enjoy your naming conventions!

Let us know what you think of those guidelines and if you have other guidelines not covered in this post by leaving a comment here.