What’s New in Alibaba’s Java Development Manual? 11 Updated Rules Explained

Hello everyone, I’m Xiao Lou.

If you write Java, you’ve probably heard of Alibaba’s Java Development Manual . I read it when I started, and it’s packed with concrete examples of good and bad code conventions, making it an essential reference.

Mandatory when using the ternary operator condition ? expr1 : expr2 , be aware that type alignment may trigger automatic unboxing, causing a NullPointerException (NPE). This occurs when either expression is a primitive type or when the two expressions have different types, forcing unboxing to the wider type. Example (bad case): <code>Integer a = 1; Integer b = 2; Integer c = null; Boolean flag = false; // a*b results in int, so c is forced to unbox to int, throwing NPE Integer result = (flag ? a * b : c); </code>

The manual covers not only code‑level conventions but also design, architecture, and database guidelines, and every Java engineer should read it thoroughly.

The first public version (1.0.0) was released in 2017. In 2019 the name changed to the “Five Peaks” series (Huashan, Taishan, Songshan), and this year the “Huangshan” edition was published, humorously suggesting that after seeing the five peaks you won’t look at other mountains.

Each new edition lists changes, but the official changelog is brief. I have extracted and annotated the 11 new rules introduced in the Huangshan edition.

Below are the newly added rules:

Programming Rules 6. Mandatory : Enum fields must be private and immutable. 3. Mandatory : Floating‑point literals must use uppercase D or F suffixes. Constant definitions Other miscellaneous rules Exception Logging 14. Recommended : Sensitive user information in log files must be masked. Exception handling Security Rules 9. Mandatory : File upload features must strictly validate file size and type. 10. Mandatory : Passwords in configuration files must be encrypted. Database 10. Mandatory : Physical deletions are prohibited; use logical deletion instead. Table creation conventions Engineering Structure 6. Mandatory : Third‑party library packages should be named with the version followed by an English description and a sequence number. Third‑party dependencies Server 1. Mandatory : Remote calls must have timeout settings. 2. Recommended : Client‑side timeout configuration order: client special method, client interface level, server special method, server interface level. 7. Recommended : Isolate slow services by configuring separate thread pools. Design Rules 7. Mandatory : Identify weak dependencies and design degradation and fallback plans to keep core systems available.

The rule about enum fields being private and immutable is particularly interesting. Below is a counter‑example that violates this rule:

public enum SwitchStatus {
    // Bad enum fields
    DISABLED(0, "禁用"),
    ENABLED(1, "启用");

    public int value;
    private String description;

    private SwitchStatus(int value, String description) {
        this.value = value;
        this.description = description;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }
}

Both value and description can be modified, which poses a serious risk if altered unintentionally. Although enums are rarely used this way, the vulnerability is real and should be avoided.