Clean Code Naming Guidelines

A qualified programmer should aim for clean, maintainable code, not just code that compiles and runs.

Good names convey the purpose, meaning, or usage of variables, methods, classes, and packages, allowing readers to understand the code quickly.

Key naming principles include:

Be unambiguous and precise.

Avoid misleading names.

Make meaningful distinctions.

Simplify names based on context.

Use searchable and readable identifiers.

Follow package‑naming conventions.

Apply class‑ and method‑naming standards.

Cost of chaotic code

Messy code slows development, introduces bugs, and reduces team productivity. Newcomers struggle to modify code they don’t understand, leading to resistance and technical debt.

What is clean code?

Clean code balances readability, extensibility, simplicity, reusability, testability, and lack of side effects. It should be easy to extend without breaking existing design, follow the Open/Closed principle, and be easy to unit‑test.

High‑quality naming patterns

Examples of poor and good naming:

• Variable example: LocalDate now = LocalDate.now(); – the name now clearly indicates the current date.

• Magic number anti‑pattern:

// From database get list
List
buyerList = dao.getList();
buyerList.forEach(x -> {
    for (int i = 1; i <= 5; i++) {
        processedBuyerList.add(String.format("%s,%s", i, x));
    }
});

Using literals 1 and 5 without context makes the code hard to understand. Replace them with named constants.

• Overly long class name: UltimateAssociatedSubjectRunBatchServiceImpl → LinkSubjectServiceImpl .

• Misleading methods: deleteIndex vs deleteIndexEx . The suffix Ex adds little meaning; a clearer name would be deleteIndexExtended or better yet a name that describes the actual behavior.

• Similar names that cause confusion: XYZStringHandler vs XYZStringStorage ; UserController vs UserInfoController . Distinguish them with purpose‑oriented verbs.

• Redundant method names: getActiveOrder , getActiveOrderInfo , getActiveOrderData , getActiveOrders . Choose a single clear name that reflects the exact intent.

• Poor method name: downloadExcel(HttpServletResponse response) that internally calls downLoadFiles and fileDownload . Rename downLoadFiles to createZipFile to clarify its purpose.

• Context‑based simplification: In class Order , fields can be named num and createTime instead of orderNum and orderCreateTime because the class context already implies “order”.

• Package naming: use all‑lowercase, dot‑separated identifiers, e.g., com.company.project.module , with optional prefixes like indi , pers , team , etc.

• Class naming: use UpperCamelCase nouns (e.g., Customer , Account ) or suffixes like Base , Impl , Utils , Exception as appropriate.

• Method naming: use verbs or verb phrases (e.g., initialize , loadAccount , save , delete ). Boolean methods should start with is , can , has , etc. Asynchronous methods may end with Async or InBackground . Callback methods often start with on , before , after .

In summary, naming is a dialogue between code and developers. Clear, purposeful names improve readability, maintainability, and overall code quality.