Writing clean code: Naming

Write code for humans, not for machines.

When you start learning how to code your main focus is writing code that works correctly for the problem you are solving. Yes, code needs to work correctly and that is a good place to start learning. However, in a real work environment, you also want to ensure you write clean code.

Clean code is readable, extensible, changeable, and maintainable. These are all important qualities for code to have.

In many professional settings, you are not writing code in complete isolation. There are other people you work with on a team. Your teammates need to be able to easily understand the code you write. They need to understand what it does, how it works, and why it was written that way. It may also be your future self coming back to code you wrote in the past and you will also need to easily understand your code.

Code is read more than it is written. To write code we are constantly reading it. So even if readable code is harder to write we should invest time to do it instead of writing easy unreadable code. Writing clean code is an important skill for any professional developer.

In this article, we are going to learn about the importance of Naming in writing clean code.

Naming is a crucial and daily task for developers in any programming language. It can either make code very hard to understand or if done well, easy to understand.

Names are all over the software developers write. When coding, you should consider naming variables, functions, arguments, classes, packages, source files, and directories that contain those source files, etc.

Below are some popular quotes on naming in programming.

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

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand” — Martin fowler

Names are the smallest building block of code. Names are the basic building block of clean code. There are some recommended rules for good naming in code. Let us discuss these rules for the rest of this article.

Use intention revealing names

The names you use in your code must be clear and understandable. Choose descriptive and unambiguous names. You should focus on the principle of least surprise. Aim to write code that other people would expect and try not to surprise them with some clever complexities.

The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name is not intention revealing.

Below is an example of code that is not intention revealing that requires a description comment and a cleaner version with better naming that does not require a description comment.

let rf = 5000 //the rental fee paid by the tenant

use the cleaner version below

let rentalFee = 5000

Classes and objects should have noun or noun phrase names

Classes and objects describe things so their names in code should be a noun or noun phrase. Names such as User, Student, Account, and ErrorLogger are good names for classes and objects. Avoid words like Manager, Processor, Data, or Info in the name of a class. A class name should not be a verb.

Methods/Functions should have verb or verb phrase names

Methods/Functions perform an action in the code so their names should be a verb or verb phrase. Names such as deleteApplication, createUser, or save are good names for methods/functions. By design, a function should have only one responsibility. If the name is anything other than a verb, then either you are naming it wrong or there are some problems in the architecture.

Make meaningful distinctions

You should try to use the same word for the same purpose across the codebase. Avoid using different but similar words to define the same concepts. The three method/function calls below could mean the same thing as an example.

FetchResult() vs GetResult() vs RetrieveResult().

For instance, don’t use fetch, get and retrieve in the same project for the same responsibility.

Use pronounceable and searchable names

When naming things in your code use words that can be pronounced rather than using non-pronounceable words.

Below is an example of a variable name that is not easily pronounceable and a cleaner version with a more pronounceable name.

Date modymdhms;

use the cleaner version below

Date modificationTimestamp;

Replace magic numbers with named constants

When you are using some constant values define them using searchable words. It makes them more understandable to other developers.

Instead of writing code like this:

let totalLoanDays = gracePeriod + 7;

create a named constant and use it like this:

const NUMBER_OF_DAYS_IN_WEEK = 7;

let totalLoanDays = gracePeriod + NUMBER_OF_DAYS_IN_WEEK;

Don’t append type information

When you name your variables avoid appending type information to them. It should be clear from the name of the variable what data it stores and developers can infer the type from there. There is no need to mention the data type in the name.

Instead of writing code like this:

let firstNameString;

let lastNameString;

use the cleaner version below

let firstName;

let lastName;

Don’t Be Offensive / Don’t Be A Comedian

Remain professional in how you name things in your code. Do not be offensive or try to be a comedian by giving a variable a funny name. Remember you are writing production code that other future software developers will need to understand easily. Your naming conventions should be generic and should not include any cultural slang.

Avoid writing code like this:

function killThemAll();

use the cleaner and professional version below

function deleteAllUsers();

Closing thoughts

In this article, we have explored some of the best practices for naming things in your code, and some things you should avoid doing. Naming may appear a small part of a software developer’s job but it is very important and can be the main difference between having a clean codebase that is a joy to work with or a complex codebase that is difficult to understand and navigate.

"One difference between a smart programmer and a professional programmer is that the professional understands that clarity is king. Professionals use their powers for good and write code that others can understand."

You should never ignore the importance of naming practices in your codebase as bad names will become a big hurdle in future development plans. Changing the codebase at that point is unnecessary overhead and can be avoided in the very beginning by following good practices.

References/Resources:

Clean Code: A Handbook of Agile Software Craftsmanship by Robert C Martin.