Code naming: How to improve the readability of your code

#codenewbie #beginners #programming

When I'm reviewing code written by junior engineers there is one common issue that I see. Often I will see functions or variables whose names are not descriptive enough.

Naming in code is important because it helps people more easily understand the code that you have written. This will help your colleagues when they come to make changes to your code in the future.

Bad naming in code makes it more difficult for anyone who is trying to read and understand the code. We say that this increases the cognitive load of the reader. They will literally need to think harder about how the code works and hold more information about it in their head.

What good naming looks like

The names you use for functions or variables should answer the following questions:

What is the effect of calling this function?
What data does this variable refer to?

Let's look at some examples.

def process_file(file_path: str) -> list[str]

What on earth does process_file() do? The name of this function is too vague because it does not describe the effect of calling this function. What processing is being done on the file? To understand what this function is doing you will have to go and read its code. This takes more time and will require the person reading this to hold more information in their head.

Let's rename the function so that it describes the effect of calling this function:

def remove_duplicate_lines_from_file(file_path: str) -> list[str]

This is much better. Now we can clearly see what this function will do with the file we pass to it. We won't have to refer to the code of the function unless we are curious as to how the duplicate lines are being removed.

Now let's look at a vague variable:

file_data = remove_duplicate_lines_from_file ('file.txt')

At first glance file_data seems like a reasonable choice. It makes sense that the function will turn the data from the file. But what actually is this data? What format is it in? What can I do with it? To answer these questions I would have to go and read the code of the function and possibly even examine the file as well.

Let's rename the variable so that it describes the data it refers to

unique_postcodes = remove_duplicate_lines_from_file ('file.txt')

Now we know what the data refers to. We can make some reasonable assumptions about the format of the data too. It's likely to be a list of strings where each string is a postcode. We can assume that the file has a postcode in each line. Perhaps even an address? This is all possible because of the choice of variable name.

Conclusion

It's easy to overlook issues with names in your code because you will be extremely familiar with the code that you write. You will not need to rely on the names you have used to understand what you have written. We've seen in the examples how good names can make code easier to understand. If code is easier to understand then it will make it easier for other engineers to maintain it in the future.

Don't stress too much about getting the name perfect the first time you write it though. The best name for something may actually change as you make progress on your code. Personally I will often rename a function or variable 4 or 5 times as I work on it so that I get the name just right.

Let's have a bit of fun now. Below is an example function in Python with poor naming. I've added a comment to explain what the function does. Add a comment with your proposal for how it should be renamed and I will review your proposal and provide feedback!

def apply_rules(items: list[Product], rules: list[Discount]) -> float
    """
    Applies discount rules to a supermarket customers basket 
    of goods and returns the total value the customer must pay 
    after all eligible discounts have been applied
    """