Arijit's blog

Coding best practices - part 1: Variable Naming

Published on

Whether you write code for fun or profit, as you gain experience, you will come across some patterns that, when followed, help you write code that’s easy to reason about, understand, write and share, in other words, just feels “right”.

Many of these patterns are well documented and accepted as standards, while many are left for us, developers to discover and follow as “Best Practices”. Here, in these articles, we’ll go through some of the patterns I currently (as of writing this post) follow and why.

Sensible variable naming

Variable naming is an art, a difficult one. While I still sometimes struggle with finding the proper name for a variable, I have seen other more experienced developers to struggle as well.

Case

One of the most important variable naming convention is being consistent with the case.

The choices are:

  • flatcase
  • UPPERFLATCASE
  • camelCase / dromedaryCase
  • PascalCase / UpperCamelCase / StudlyCase
  • snake_case / pothole_case
  • SCREAMING_SNAKE_CASE / MACRO_CASE / CONSTANT_CASE
  • camel_Snake_Case
  • Pascal_Snake_Case
  • kebab-case / dash-case / lisp-case
  • doner|case
  • TRAIN-CASE / COBOL-CASE / SCREAMING-KEBAB-CASE
  • Train-Case / HTTP-Header-Case

source

Many programming languages will enforce their opinions, while many require us to know and follow their recommended naming convention. Some programming languages doesn’t even come with recommendation, and hence cause a lot of debates between individual and/or team preferences.

If a programming or scripting language doesn’t have a recommendation, here’s what I follow:

  • Use SCREAMING_SNAKE_CASE for globally defined variables.
  • Use snake_case for local variables and function names.
  • Use PascalCase for class or struct definitions.

Yes, it looks like Python’s recommendations as I have a lot of experience with this language and agree with a lot of its Zen.

Character length

In most schools and colleges (at-least in my college), we were taught to use variables named x, y, z everywhere, even if they’re not co-ordinates. Names like these make is really difficult to make sense of code. While, in some enterpricy softwares, you may find names like someVeryLongaAndAbstractVariableName. If I ever find myself naming variables like this, I know it’s probably time to refactor my code, i.e. split it into separate modules or scopes (e.g. some.very.long.and.abstract.variableName). While this name still feels long, it’s now possible to declare an alias like var = some.very.long.and.abstract, and use the alias instead (e.g. var.variableName).

It’s fine to use short variable names like x, y, z in very small scopes, e.g. in lambda functions or functions with up to 10 lines of code, where there isn’t a lot of variable definitions in it. Using longer names in such cases is not only inconvenient, it in my opinion, makes the code slightly difficult to read.

Context

This is the most difficult part of naming variables. The variables that are not just aliases, should be able to express a lot of its purpose, nature and context of the logic via its name. But, most often, while writing code, we’re not sure what these might be, because in programming, we don’t generally plan too ahead. Sure we keep the ultimate destination in mind and aim to reach it, but each little bit of logic required to reach that goal, has their own implementation and goal that are not defined.

In such cases, where I’m not sure whether or not the variable name I come up with is good enough or bad, or if I know it’s bad but can’t do any better, I use the name that’s the closest and use comments to define what the variable is, what it does etc. This way, others reviewing the code, if finds the variable name confusing, can read the comments and even come up with a better name suggestion.

Conclusion

One thing you will come across for sure is that, different people have different opinions. Some may feel very strongly about how variables should be named. This is because, naming convention requirements differ between technology stack, domain and even personal preferences. You can have your own opinions. But the most important part is being consistent. For example, don’t use snake_case in one file and camelCase is other, unless they are really meant to be different.