Why Good Naming Matters: 10 Practical Tips for Readable Code

01 Why naming is important?

In a project, every class, method, variable, and parameter starts with a name; poor or confusing names make code hard to understand and can mislead the reader, while good names give a clear, pleasant start and guide future developers.

02 Why is it hard to name correctly?

Many developers lack the will, the thinking, or the technique to choose proper names, often picking names based on personal preference without considering the purpose, responsibilities, or potential misunderstandings.

03 How to name correctly?

The article focuses on practical naming advice using Java as an illustration, without tying to language‑specific rules.

1. Be descriptive

A name should answer the big questions: why it exists, what it does, and how it should be used. If you still need to read a comment to understand it, the name is not descriptive enough.

Case 1: How to decide what "End" means?

public interface OnRequestListener {
    /** 请求结束 只有成功点才认为是真正的结束 */
    void onRequestEnd(...);
    /** 请求开始 */
    void onRequestStart(...);
}

Suggested refactor:

public interface OnRequestListener {
    void onStart(...);
    void onSuccess(...);
    void onFailure(...);
}

2. Avoid misleading names

Do not reuse built‑in identifiers for unrelated concepts.

Case 2: Misleading collection name

private List<SectionModel> dataSet;

Suggested rename:

private List<SectionModel> dataList;
// or
private List<SectionModel> sections;

Case 3: "View" suffix without extending a view

public class RItemOverlayView { }
public class NRItemOverlayView { }

Rename to reflect purpose, e.g., ItemOverlayViewCreator placed in appropriate packages.

3. Use meaningful distinctions

Avoid using numbers or vague prefixes when they add no meaning.

Case 4: Numeric package names

Replace recommend2, recommend3, etc., with descriptive names that convey the scenario (e.g., recommendFavorites, recommendHome).

4. Use readable names

Prefer full words or well‑known abbreviations over cryptic shortcuts.

Case 5: Unclear variable abbreviations

private LinearLayout mTabLL;
private TabLayout mTabLayout;

Rename to:

private LinearLayout mTabLayoutParentView;
private TabLayout mTabLayout;

5. Use searchable names

Give constants and magic numbers meaningful identifiers.

public static final String FESTIVAL_ON = "1";
public static final String NAV_STYLE_FESTIVAL = "0";
public static final String NAV_STYLE_SKIN = "1";
public static final String NAV_STYLE_DARK = "2";

6. Class naming

Use nouns at the end (e.g., OrderService, CancelOrderCommand) to indicate the entity’s role.

7. Method naming

Use strong verbs with clear targets; avoid vague verbs like process or handle unless the purpose is explicit.

/** 是否有浮层数据 */
private boolean hasFloatData(MainPictureData data) { ... }

Rename ambiguous methods such as processMainPic to hasMainPictureFloatData for clarity.

Source: Alibaba Developers

Further reading includes articles on software engineering, REST API naming conventions, and how to choose good variable names.