What the New Alibaba Java Development Manual Reveals About Clean Code Practices

Introduction

The author habitually reads every new version of the Alibaba Java Development Manual and updates the corresponding IDEA plugin to enforce the standards. When the latest "Taishan" edition was released on April 22, the author revisited the manual as a mirror for improving code quality.

Key Takeaways from the Taishan Edition

After three hours of reading, the author identified 34 new mandatory rules and 90 modifications compared with the previous version. Selected examples are listed below.

Rule 1 (Mandatory): Array type must be written with brackets attached to the type, e.g., int[] arrayDemo;.

Rule 2 (Mandatory): Package names use singular form; class names may be plural when appropriate, e.g., package com.alibaba.ei.kunlun.aap.util and class MessageUtils.

Rule 3 (Mandatory): Use a non‑null object or constant when calling equals to avoid NullPointerException. The manual recommends java.util.Objects.equals(a, b). Example implementation:

public static boolean equals(Object a, Object b) {
    return (a == b) || (a != null && a.equals(b));
}

Rule 4 (Mandatory): Compare wrapper‑type integers with equals rather than ==.

Rule 5 (Mandatory): Store monetary amounts in the smallest currency unit using integer types.

Rule 6 (Mandatory): Do not compare floating‑point numbers with == (primitive) or equals (wrapper). Use an epsilon range, e.g.:

float a = 1.0f - 0.9f;
float b = 0.9f - 0.8f;
float diff = 1e-6f;
if (Math.abs(a - b) < diff) {
    System.out.println("true");
}

Rule 7 (Mandatory): Avoid new BigDecimal(double) because of precision loss; use BigDecimal.valueOf(double) or construct from a String.

Rule 8 (Mandatory): Use isEmpty() to check collection emptiness instead of size() == 0 for O(1) performance and readability.

Rule 9 (Recommended): Initialise collections with an explicit initial capacity, e.g., new HashMap(16).

Rule 10 (Mandatory): When concurrent updates may cause lost updates, apply locking – optimistic or pessimistic – with guidelines on when to choose each and a minimum of three retry attempts for optimistic locks.

Rule 11 (Recommended): For financial‑sensitive data, prefer pessimistic locking rather than optimistic locking.

Rule 12 (Mandatory): In high‑concurrency code, avoid using equality checks as loop‑exit conditions; prefer range checks.

Conclusion

The Alibaba Java Development Manual serves as a detailed mirror for developers, helping identify hidden issues and adopt cleaner, more reliable coding practices. Regularly consulting the manual can significantly improve code quality, readability, and maintainability in backend Java projects.