NOTEPAD

Naming things

There are only two hard things in Computer Science: cache invalidation and naming things.
Phil Karlton

Mr. Karlton was a prominent american computer scientist who worked mainly in the 80s and 90s, among other places, in Netscape.
By the way, if you feel curious you can check out his page here.

This is the way web was in Netscape times. Those were the weapons used to fight the browser wars in the 90s!

Is it really that important to name variables properly?

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
Martin Fowler

Code is due to be read by humans, a lot more than it is intended to be interpreted by a computer. It must tell its story clearly and concisely, and naming things is a huge part of it.

And names of variables and functions serve as implicit documentation and are instrumental for program comprehension.

Names have contents and form, and will compound the environment where developers will try to make their part.

In large open source projects about a third of the tokens are identifiers, and they account for about two thirds of the characters in the source code.

So it's not that hard to figure out the answer to the question above, right?

Conventions

There’s a number of naming styles; it may depend on:

  • object to name
  • programming language
  • convention choosed

Object to name

In C# (for example) we see that while classes and methods are usually written in Pascal case, local variables and parameters use camel case.

So customs and habits may vary from language to language, but commonly used naming styles are:

camelCase: capitalizes the first letter of each word in a phrase, except for the first letter of the entire phrase, which can be either uppercase or lowercase. We can find it used in Java, Kotlin, JavaScript. (More)

UpperCamelCase (o PascalCase): same as camel case, but it started in uppercase. In some languages, as mentioned, it is used to name classes.

snake_case: words are separated by underscores. For example, it is encouraged by Python’s style guide (PEP8). (More)

kebab-case: words are separated by hyphens. Very commonly used in URLs, for example. Also in CSS styles definitions. I've seen very often in HTML ids and classes too.

UPPER_SNAKE_CASE: same as snake_case, but uppercase. Also called SCREAMING_SNAKE_CASE, and is commonly used to define constants, together with simple UPPERCASE style.

Clearly, all this wit game mainly focuses on avoiding spaces between words. Spaces make the compiler/interpreter's life harder.

Conventions

Each team chooses the best convention to follow. Of course, a convention is as good as the team commitment to follow it.

Naming convention table

Programming language conventions

The soul of variable names

We want to ask a variable several things about its name:

  • Why is it named the way it is?
  • What does it contains?
  • What does it do?
  • How is it used?

These are a lot of questions, right? How a reasonably succinct variable name will answer all of that? OK, we may not get all the answers from it, but let's remember that our variables work in a context and follow a set of agreed criteria, so it is correct to hope that the names contribute to answering these questions.

When we say that a variable name should be "meaningful," we mean that the name of the variable should clearly and accurately reflect the purpose or meaning of the data it represents. In other words, the variable name should provide relevant information about the data it stores or manipulates, making it easier for programmers to understand the role and context of the variable within the code.

Meaningful variable names contribute to the readability and maintainability of the code, as they make it easier for other programmers (or even the original programmer at a later time) to understand the code's logic and functionality without needing to decipher cryptic or unclear variable names.

For example, instead of using a generic name like "x" or "temp," a meaningful variable name like "numberOfStudents" or "totalSales" provides clear information about what the variable represents and how it is used in the code. This makes the code easier to understand, debug, and modify in the future.

Choosing a correct name takes time! But you save more than you spend.

Names are a design choice.

How to choose the words that make up a name

variables > nouns

Variables represent entities or concepts. When you name it with a noun, we are identifying the information contained.
"name", "age", "average", "house", "amount".

functions > verbs or verb phrases

It should show what the function does.
"calculate", "deleteItem", "register", "addMember", "terminate".

properties > adjectives

Adjectives could be useful adding details about variable names, classes or methods. It purpose or usage should be clear. "current_temperature" (a variable with a noun and an adjective), "order_boxes_desc" (a method with a verb, a noun and an adjective)

classes > nouns

As with variables. A class name should not be a verb.
"Customer", "Account", "Company", "BankAccount". Avoid words like "Manager", "Processor", "Data", or "Info".

Qualifiers:

If you modify a name with a qualifier like Total, Sum, Average, Max, Min, Record, String, or Pointer, put the modifier at the end of the name. One usual qualifier is "count", when referring to quantity or number.
Examples: "monthRevenueAverage", "salaryMax", "expenseTotal", "customerCount".

Accessors and mutators… always with "get" and "set". "getName", "setName".

Boolean values:

usually boolean variable names are preceding with "is" prefix.
Examples: "isAuthenticated", "isVisible", "isValid" Another commonly used prefix for that is "has".
And we can also find several other prefix that aren´t uncommon: "can", "should", "will", "do".

Of course those are just advice. I just think on them when trying to find a good variable name. Generally speaking, the key to create a good name effectively is using descriptive and precise words. When achieved, code end up being easier to understand and also maintenance.

Bad naming impairs program comprehension and consequently increases the effort that developers must spend to maintain the software.

Long or short?

The lenght of a name should correspond to the size of its scope
Robert C. Martin - Clean Code
  • Don´t be afraid of long names, as long as they’re not names on which we didn´t invest the right amount of effort to build them
  • ...but be aware that long names takes more cognitive energy to be read and understood. They can clutter the code, therefore making it uncomfortable.
  • Avoid lowercase "l" and uppercase "O" when possible, for they can be confuse with "0" (zero) or "1" (one), depending on the typeface used by the developer.
  • Try names that are pronounceable.
  • Using loose letters is probably a bad idea. In any case, reserve them for local scope only. Of course, letters "i", "j" and "k" are very often find in "for" and "while" loops.
  • Do not use "var" or "variable".
  • Remember to make names that can be search for. Think about it on names that are going to be used in many places.
  • Full names are better than abbreviations. Comprehension is faster with full and descriptive names. Abbreviations sometimes carry some additional cognitive load.
  • Maybe is better not including the object type or data in the name. "name" is better than "str_name", "customer" is better than "customerObject", "money" is better than "moneyAmount"... you get the idea.
  • But put unit sizes in them (for example, "seconds", "meters", and so forth)

If teams agreed on naming strategies, for example picking a mold to be used along the projects, cognitive load on team members improves on naming things.

How long then?

Some studies show that the effort required to debug a program was minimized when variables had names that averaged 10 to 16 characters. Programs with names averaging 8 to 20 characters were almost as easy to debug.

The process of creating names

All the names will create a context that will guide the programmer and make him feel more or less comfortable in the project environment.

We can try this three step process:

  1. selecting the concepts to include in the name.
  2. choosing the words to represent each concept. Pick One Word per Concept
  3. constructing a name using these words

Sometimes if you find yourself struggling to naming something, think about your code structure, for this may point to some issues there.

It is worth to check for naming smells, for example:

  • if a naming method of function do more than its name says
  • if a naming method of function do less than its name says
  • if a naming method of function do the reverse of what its name says

Be open to rename things. Do not expect to naming things right on the first try. Your code will evolve, and you may need to iterate over the names you place in it along with everything else. Remember that you improve your understanding of any complex problem you're facing as you work on it!

There is a chance of 7% that two developers choose the same name for a variable.
Dror G. Feitelson et al - How developers choose names

Finally

Just for fun, check this two more versions of the cite at the top!

There are only two hard things in Computer Science:
0. cache invalidation
1. naming things
2. off by one errors

And one more:

There are only two hard things in Computer Science:
0. cache invalidation
1. naming things
47. asynchronous callbacks
2. off by one errors

There is much more to naming variables. Here I only mention some things that I found while browsing the web and others that I read in the mentioned books. In my opinion, the main mandate is to assume the relevance of the issue and assign proper time to it, so that the next programmer who reads our code understands it with as little effort as possible. Remember, it may be ourselves...