Code Naming: 5 Rules That Keep Code Readable

27 September 2024 Engineering

In software development we love complex topics: SOLID, DRY, design patterns. Meanwhile one of the simplest things, code naming, quietly decides whether the code will be readable in a year. This article is about why names matter and how to make them work for you.

The cost of a bad name

Code with poor naming is a maze without signs. It slows everyone down and raises the chance of mistakes. When you return to such code months later, you usually face three scenarios:

A full refactor, which increases the amount of work and the risk of new bugs.
Targeted patches that make the code even more confusing.
Surface changes without analysis, which skip important details.

What good code naming gives you

Faster understanding of the code.
Less time on refactoring and debugging.
Easier onboarding for new developers.
Better communication inside the team.
Less need for redundant documentation.

Readability: from calc to a sentence

This works, but its purpose is not obvious at a glance:

def calc(n1, n2, op):
    if op == '+':
        return n1 + n2
    elif op == '-':
        return n1 - n2
    elif op == '*':
        return n1 * n2
    elif op == '/':
        return n1 / n2 if n2 != 0 else "Error: Division by zero"
    return "Error: Invalid operation"

Now with names that explain themselves:

def perform_arithmetic_operation(first_number, second_number, operation):
    if operation == '+':
        return first_number + second_number
    elif operation == '-':
        return first_number - second_number
    elif operation == '*':
        return first_number * second_number
    elif operation == '/':
        return first_number / second_number if second_number != 0 else "Error: Division by zero"
    return "Error: Invalid operation"

The function now says what it does without a single comment.

Preventing bugs: a hook must look like a hook

In React, the use prefix is a contract. Rename the function and the rule becomes visible:

function getData(url) {
  const [data, setData] = React.useState(null);
  React.useEffect(() => {
    fetch(url).then(r => r.json()).then(setData);
  }, [url]);
  return data;
}

getData is actually a hook, but the name hides that. Calling it inside a click handler breaks the rules of hooks. The fix is one word:

function useDataFetching(url) {
  const [data, setData] = React.useState(null);
  React.useEffect(() => {
    fetch(url).then(r => r.json()).then(setData);
  }, [url]);
  return data;
}

Now it is obvious that useDataFetching must be called at the top level of a component.

Making code searchable

In a large project, names like these are impossible to search:

function process(data) { /* ... */ }
function handle(info) { /* ... */ }
function manage(userData) { /* ... */ }

Descriptive names make search work again:

function processUserRegistration(userData) { /* ... */ }
function handlePasswordReset(userCredentials) { /* ... */ }
function manageUserPreferences(userSettings) { /* ... */ }

Conclusion

One reference worth keeping: the naming convention overview.

Good naming is not cosmetic. It is a tool for building code that is understandable, maintainable and cheap to change. Spend a minute on a name today and save an hour for yourself and your colleagues next quarter.

Questions about renaming

Should I rename old code? Rename when you touch it. A global rename without tests is a separate project.

Are short names bad? Only when they hide meaning. A loop index is fine; a business entity called data is not.

What about abbreviations? One meaning per project. If usr means user in one file and usage in another, the name is broken.

If the name needs a comment, the comment belongs in the name.

Names are read far more often than they are written.

The importance of correct naming in code