Good Variable/Function/Class Naming

• see,
  • best practices,

Some people claim that variables, functions, class (actually, whatever comes with a name) should follow some global rules like “they should be long and contain no abbreviations” or on the contrary “they should be as short as possible”.

To me, claiming those rules is loosing the sight on the final objective of naming things, which is communicating with other human beings.

Indeed, the machine does not care at all whatever name you gave to your stuff, but your future self or coworkers care.

When people invoke some great principles, like “as short as possible”, I feel like they just shout out some recent frustration rather than actually think about communications. Great principles might be useful if actually supported by neuro science showing objectives reasons to believe it. If it is only a matter of opinion, I don’t see why some great principle’s opinion might be better than others or none at all.

I agree that blindly following great principles helps not thinking about this aspect and be faster writing code. But I encourage you to think twice at your values and consider what doing your best means here. To me, readability counts.

I think that the sole great principle is “what makes the most sense for the people that will read the code”. Of course, this is a more difficult question and question substitution happening in our brain is happy to just answer “what great principle was I told”.

To me, if you actually want to make the code more readable, the best you can do is read the code and follow your gut feeling. With experience, this gut feeling will tend to be more and more reliable¹.

Remember that you play the game of communication. You need to lean on the context. Also, the person reading the code will try to honestly understand your intention.

For instance, if at some point you need to have a variable about the “united state of america”, and you think that the code is obviously enough dealing with countries, then there is no issue naming the variable “USA”. On the contrary, if you need to name something totally different that would be named something like “unique simple assistant”, then you might want to think twice before naming it USA.

Another example, may be a bit stereotypical:

To me, this code

map_of_names_to_ducks = {}

map_of_names_to_ducks["donald"] = Duck(...)
map_of_names_to_ducks["daffy"] = Duck(...)

Is much less readable than this one

names_to_ducks = {}

names_to_ducks["donald"] = Duck(...)
names_to_ducks["daffy"] = Duck(...)

Or this one

ducks_map = {}

ducks_map["donald"] = Duck(...)
ducks_map["daffy"] = Duck(...)

And definitely this is the best naming in this situation.

ducks = {}

ducks["donald"] = Duck(...)
ducks["daffy"] = Duck(...)

Because naming the type is not useful for the reader to understand that this variable stores ducks and that they are accessed using their name.

Permalink