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.
- 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.
- 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.
- 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
- 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.
- 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:
- Delimitation - either using CamelCase or under_scores.
- Consistency - always have the same type of information in the same portion of the variable. (e.g. don’t have HorseSpeedMPH and MPH_DonkeySpeed.)
- 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:
- Use standard abbreviations where possible (e.g. MPH is known to be miles per hour)
- Try to use between 2 and 4 characters for the abbreviation
- 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.
2 CommentsOldest to Newest
These are some good points, but are not specific to Simulink / Model Based Design per se.
Do you have thoughts on any of the following?
– letting Simulink handle units for us via port units
– naming signals (lines between blocks)
– block names:
hide them? customize them for the block’s purpose (e.g. call a switch block “input selector”)? leave them auto-generated (switch1)?
I agree with you completely that these suggestions are not just for the Simulink world, that was in truth part of the intent to write something that would bridge both worlds. With respect to your questions
1.) Units: I tend to follow a data driven approach when modeling, because of this I would place the unit information in with the Data using the “Units” field in Simulink Data Objects. For more information on units in SImulink you can follow this link:
2.) Naming signal between blocks: In my models only about 10% of the “between blocks” signals get a signal name. The reason for that is they are, for the most part, intermediate calculations and not something I need further down stream. Occasionally I will name a signal or create a test point for a signal if I need it for diagnostic reasons.
3.) Block names: On block names I fall back to the MAAB rule JC_0061. A short summary of it would be “Only give and display the name if it has a unique meaning.” E,g, I don’t need to see “Add2”, “Add3”, “Add4” in my model view