Practical tips on naming

Naming is hard.

Everyone in software engineering has stumbled on hard-to-understand variable/method/class names. And almost certainly everyone has paused while writing code to think what a variable/method/class should be named to be descriptive enough for the future reader.

Even though there are no strict rules we can set in naming things to make it a consistent and repeatable process, there are some rules we can agree to make naming more consistent (and thus improve readability).

I think that naming rules should be agreed upon as part of the code style of a team. Even if that's not the case, being self-consistent with naming things will help your code to be easier to understand by others (and by the future self who forgot what you meant 3 months ago).

Not too short, not too long

Naming a variable r is as unreadable as netRevenueForTheLastCalendarYear.

Single letter identifiers are obviously not a very readable choice. If you find yourself naming something with a huge but descriptive identifier think again though. Too long names are hard to parse and generally make things harder to remember.

I don't believe there's a max number of characters for the ideal identifier. I do believe though the ideal length is somewhere between 1-4 "words" (words in camel-case). Aim for the sweet spot of a readable but short name.

Do not repeat the class name

class RevenueEmailer {    fun sendRevenueEmail() { [...] }}

An instance of the above class will most probably be stored in a variable named revenueEmailer, leading to calls of revenueEmailer.sendRevenueEmail().

Make things shorter by avoiding the context. No need to repeat the class name. Instead, mention only the new information. A sample call, in this case, would be revenueEmailer.send().

class RevenueEmail {    fun send() { [...] }}

Disambiguate when needed

val anualNetRevenueForCompanyA

An overly specific identifier is justified when there are too many similar identifiers.

But there's no need to have such long names when there's no need to disambiguate between similar and confusing items. Instead, omit everything except the necessary.

val anualNetRevenue

(Optional) Avoid stop and generic words

Avoid, when possible, stop-words (e.g. "from", "to", "for") from identifiers. The same goes for generic words (e.g. "data", "helper", "util") that do not add any real information about the function of the item.

I say "optional" here because I think there are cases these words are actually useful and needed for the name to make sense. As usual, use your best judgment.

Few things are absolute in software engineering. Naming is certainly one of the most subjective things. So take the above "rules" with a pinch of salt, choose whatever you like, and modify them to fit your needs.

The important thing, in my opinion, is to be self-consistent, and ideally team-consistent.

Happy coding!