Up: Software engineering principles
Six rules of naming
In my talk The importance of naming, I set out six naming principles:
-
Use only one name to refer to a concept. Each concept must have one name only. If a concept has multiple names, decide on its canonical name, and stop using other names.
-
Give different concepts different names. Each name must be used for one concept only. If a name refers to multiple concepts, decide on its canonical concept, and stop using it for other concepts.
At SoundCloud, “mri” referred to three different things, and so did “go.”
-
Rename concepts when principles are violated. I expect principles to be broken over time, as software evolves. Make renaming quick and easy.
-
Ensure names match meaning. A name is no good if it is difficult to remember what it stands for, or when it seems to fit another concept better.
-
Break up concepts that cannot be named properly. If a single concept cannot be named appropriately, it is likely that this single concept is a set of multiple concepts, in the guide of a single one. Note that breaking up a concept could require many changes, including database schema changes.
-
Be consistently correct. Consistency brings predictability, and predictability keeps cognitive overhead low.
Don’t get fancy with names
Let me start with examples:
Homebrew has “taps” and “kegs” and “casks” and “formulas” and “bottles” and a “cellar.” What do those names mean? Even through I have used Homebrew for years, I would not be able to explain to you what exactly the differences between all these things are.
At SoundCloud, there first was a service named FIST, then one named ARMS, and finally one named SHOULDERS. Especially the latter service names made no sense. SoundCloud also had “moshimoshi” and “okidoki” and many other badly named services (I’m leaving out my own contribution here).
Make the data kind/unit clear
See Naming principle: clear kind or unit.
Keep names clear within their immediate context
Generally, a name needs to be understandable by itself.
However, for variables that have limited scope, the immediate context can be helpful for determining the meaning of names. Take this code snippet in a fictitious language for example:
for (var i = 0, i < bytes.len, i++) {
var b = bytes[i]
buffer.push(b)
}
The variables i and b have a short name, but also have limited scope (2–3 lines). Because the scope is so small, these short variable names are fine.
Miscellaneous
Create a glossary. Keep maintaining that glossary.
Use deprecation mechanisms that your language or frameworks provide. Source code comments can be appropriate for that purpose.