Why Good Naming Is the Secret Weapon for Clean Code

Introduction

Naming is an exploration of a thing's essence and a promise to the reader; a poor name leads to confusion like a fog, while a good name acts as a lighthouse that guides understanding.

"The three difficulties of translation: fidelity, expressiveness, elegance." — Yan Fu

Bad Naming Example

The following code demonstrates a vague name that hides intent:

public List<int[]> getThen(){
    List<int[]> list1 = new ArrayList<int[]>();
    for (int[] x: theList)
        if (x[0] == 4)
            list1.add(x);
    return list1;
}

The problems are not the code’s brevity but its lack of context: the type of theList, the meaning of the index 0, the significance of the value 4, and how the returned list should be used are all unclear.

Improved Naming

Renaming the method and variables clarifies purpose without changing logic:

public List<int[]> getFlaggedCells(){
    List<int[]> flaggedCells = new ArrayList<int[]>();
    for (int[] cell: gameBoard)
        if (cell[STATUS_VALUE] == FLAGGED)
            flaggedCells.add(cell);
    return flaggedCells;
}

Further modeling the data improves readability even more:

public List<Cell> getFlaggedCells(){
    List<Cell> flaggedCells = new ArrayList<Cell>();
    for (Cell cell: gameBoard)
        if (cell.isFlagged())
            flaggedCells.add(cell);
    return flaggedCells;
}

Two key changes are evident: the raw int[] is replaced by a meaningful Cell model, and the magic constants are hidden behind expressive methods.

Naming Principles

Accuracy (信) : the name must convey the exact meaning.

Fluency (达) : the name should read smoothly.

Elegance (雅) : the name should be concise and graceful.

Bad Naming Patterns

Avoid generic terms like accountList unless the type is truly a list; prefer accountGroup or accounts.

Avoid confusing characters such as lowercase l and uppercase O.

Meaningful Differentiation

When multiple identifiers exist in the same scope, give them distinct, descriptive names (e.g., source vs. destination for a copy routine).

public static void copyChars(char source[], char destination[]){
    for (int i = 0; i < source.length; i++){
        destination[i] = source[i];
    }
}

Consistent Style

Maintain uniform naming conventions across a project: same case for loggers, consistent getter/setter names, and unified comment style.

Refactoring Process

Renaming is an iterative activity. Start with a provisional name, commit the change, and later replace it with a more precise one after testing.

Simple Rename

Change the declaration and update all call sites, then run tests.

public long circumference(long radius){
    return 2 * Math.PI * radius;
}

Migration Rename

When a method is widely used, extract the old logic into a new method, redirect callers, and finally inline the old method.

public class SearchConditionAssembler {
    public static SearchCondition assemble(String labelKey) {
        String json = getJsonSearchConditionFromCache(labelKey);
        return assembleSearchCondition(json);
    }
}

Conclusion

Good naming is an art that brings code closer to its essence. Clear, self‑explanatory identifiers reduce the need to read implementation details, improve maintainability, and support collaborative development.