How To Name Your Code?

How often has it happened to you that you understand the code written by others at first glance?

Probably not often. You need to dive deep into the code to understand what’s going on and go through it multiple times.

Even so, you might not comprehend the code’s functionality.

What could you do to avoid such instances?

Here’s when clean code comes to the rescue.

Clean code encourages you to write code that works and is easy to understand by other developers.

For instance:

function city(a, b) {
	print('I am moving from city', a, 'to', b)
}

How much of it do you understand what task the function is performing at first sight?

The function’s name is not descriptive enough to describe its intention. Nor are the variable names meaningful.

Compare the above code snippet with this one:

function printCity(fromCity, toCity) {
	print('I am moving from city', fromCity, 'to', toCity)
}

Here the name of the function is self-explanatory, and the variable names give us clues that the cities denote the start and end of something.

The cryptic code has become much more readable just by changing the names.

Such easy-to-read code makes the lives of other developers easier and helps you in debugging as well.

If you want to make your code meaningful, maintainable and legible, below are some rules to keep in mind while naming it.

Naming conventions for clean code

Now that we are over the importance of clean code let’s look at some naming conventions to help you write readable code.

The conventions described here are independent of the programming language you use.

These work parallel with the conventions described for the programming language you code in.

Rule 1: Use nouns or short phrases with adjectives to name variables

Variables in most programming languages are nothing but data containers.

They hold some data for storing or processing.

It is advisable to name them with nouns or short phrases with adjectives to clarify the meaning of the data stored.

For example:

let f = {}

Here, the variable name ‘f’ tells us nothing about the stored data.

What is ‘f’ here? Customer details, product details or something else?

We have no clue.

But, if we were to store some user details in it, we could name it something like:

let user = {}

We could also use names like ‘userData’ but, as we use objects for storing data, appending the word ‘data’ adds no value to the name.

Aim to avoid redundancy in names as much as possible.

Comprehend if appending an extra word to the name will add any value.

Rule 2: The names of the booleans must resolve to a yes or no answer

Let’s look at an example,

if (login) {
	// do something
}

Here, login is a boolean, but the variable’s name is not clear enough to derive meaning from its name.

What does ‘login’ mean? The action of logging in? Has the user logged in?

We can’t understand.

Instead, we could name it something like,

if (isLoggedIn) {
	// do something
}

Here, the variable’s name is meaningful enough to conclude that it signals if the user is logged in. The answer to the question ‘Is the user logged in?’ could be a yes or no.

Booleans have an on/off nature. As such, their names must reflect their character.

Rule 3: Use verbs or short phrases with adjectives to name functions or methods

Functions are the doers in programming languages.

They act as a command to execute something and may return a result.

Verbs in a language are action words.

So naming functions with verbs makes sense in that they shall describe the action they need to perform.

For example:

function getUser() {
	// do something and
	return user
}

The verb ‘get’ here tells us that the function will get the user details.

It could do so through a network request or by fetching it through a database.

Either way, we could conclude that the function will ‘get’ the user’s details.

We could also use ‘fetchUser’ here. The only condition is to use the same verb, i.e., ‘fetch’, for all functions, implying that it gets data. To understand this better, let’s look at a code snippet.

function getUser() {
	// do something
	return user
}
function fetchAdmin() {
	// do something
	return admin
}

We have functions ‘getUser’ and ‘fetchAdmin’ in the above code sample.

Both perform the same task of getting the user’s details but use different verbs.

In such instances, it is essential to use either ‘get’ or ‘fetch’ as the action word for both functions to avoid confusion.

Avoid inconsistencies when using verbs for naming functions and stick to using the same verbs for the same actions.

Rule 4: Use nouns or short phrases with nouns to name classes

Classes in most programming languages instantiate something.

It could be a user, product, review, etc.

It is advisable to use nouns to describe instantiated things for naming classes.

Let’s look at an example:

class User {
const firstName;
const age;
const email;
}

The above code snippet defines a class User which instantiates like:

let user = new User(); Here, the name ‘User’ is meaningful enough to understand it instantiates a user.

We could use names like ‘AppUser’, but the word ‘App’ does not add value. Every user is an application user, so what does ‘AppUser’ mean?

Going by the previously stated rule, avoid any redundancies when naming your variables, functions or classes.

Another example,

If a class is responsible for connecting to the database, name the class Database instead of using names like DatabaseManager.

The word ‘Manager’ distorts the meaning of the class Database.

‘Manager’ of what? Is the user a ‘DatabaseManager’?

To avoid any confusion, make sure to use nouns and think before adding an extra word to the name. Does it add any value, or does it make the meaning fuzzier?

I hope the tips provided help you to write cleaner code in the future and make your life easier.

If you have any questions or comments, feel free to add them in the comments sections below.

Till then, Happy Coding!

References:

Clean Code