Explore the Updated Java Development Handbook: 21 New Rules & Key Code Pitfalls

Announcement

Alibaba releases the updated Java Development Handbook , now renamed simply as the "Java Development Handbook" to thank the global Java community. Over 2.6 million engineers have downloaded the previous version, and the new edition adds three major upgrades.

Major Upgrades

1. 21 New Rules covering issues such as null‑pointer risks in switch, floating‑point comparison pitfalls, type confusion without generics, lock/unlock considerations, and date‑format problems.

2. 112 Description Revisions improving explanations for IFNULL checks, toArray length handling, and log placeholder usage.

3. Enhanced Examples including variable naming, guard statements, enum usage, and finally return behavior.

Key Technical Highlights

Lock Usage – Improper lock handling can cause deadlocks. When acquiring a lock, ensure no method that may throw an exception is called between the lock acquisition and the try block; otherwise the lock may never be released, leading to IllegalMonitorStateException on unlock.

Switch NPE Issue – When the switch expression is a String that may be null, a null‑check is required. Example:

public class SwitchString {
    public static void main(String[] args){
        method(null);
    }
    public static void method(String param){
        switch(param){
            // not reached
            case "sth":
                System.out.println("it's sth");
                break;
            // not reached
            case "null":
                System.out.println("it's null");
                break;
            // default case
            default:
                System.out.println("default");
        }
    }
}

Floating‑Point Comparison – Decimal numbers like 0.1 cannot be represented exactly in binary, so float a = 1.0f - 0.9f; and float b = 0.9f - 0.8f; may yield different results. Direct == comparison or Float.equals() is unreliable; use an epsilon tolerance instead.

float a = 1.0f - 0.9f;
float b = 0.9f - 0.8f;
if (a == b) {
    // expected but false
}
Float x = Float.valueOf(a);
Float y = Float.valueOf(b);
if (x.equals(y)) {
    // expected but false
}

Guard Statements – To avoid deep nested if‑else chains, use guard statements or design patterns. Example:

public class GuardStatementsDemo {
    public void findBoyfriend(Man man) {
        if (man.isBadTemper()) {
            System.out.println("月球有多远，你就给我滚多远.");
            return;
        }
        if (man.isShort()) {
            System.out.println("我不需要武大郎一样的男友.");
            return;
        }
        if (man.isPoor()) {
            System.out.println("贫贱夫妻百事哀.");
            return;
        }
        System.out.println("可以先交往一段时间看看.");
    }
}

Collection to Array – When converting a collection to an array, the provided array size should be zero; this works correctly even under high concurrency.

ScheduleService Removal – The rule detecting ScheduleService creation was removed after evaluating its practical impact.

Download

Scan the QR code below to download the latest handbook for free.

We thank all contributors for their suggestions, which helped refine the handbook and correct historical errors.