Reading the Alibaba Java Development Manual

Alibaba recently released the Java Development Manual (Taishan Edition). I spent some time with it and jotted down a few reflections.

Why conventions matter

• Some developers dislike rules, but imagine ten teammates each following different styles. With overlapping code, maintenance becomes a nightmare. Consistency enables collaboration.
• Standards lower the barrier to contribute and make code faster to read. When everyone follows the same patterns, bug rates drop.
• Even solo developers benefit from personal conventions. Standardization boosts efficiency over time.
• These guidelines are distilled from countless bugs and lessons learned. They may not be perfect, but they’re worth studying.

Skipping conventions might work today, but problems accumulate and eventually hurt everyone involved.

Tooling: lint

• Teams often fluctuate and skill levels vary, so we rely on tooling—Checkstyle, the Alibaba IDE plugin, ESLint, etc.—to enforce baseline conventions.
• Linting is only one layer; merge requests and code reviews reinforce the same goals: uniformity and quality.

Rules worth revisiting

1. FIXME marks an issue that needs immediate attention; TODO marks something to handle later. IDEs like IntelliJ/WebStorm recognize both.
2. Avoid magic values:

   const data = ['foo', 'bar', 'baz'];
   const dataLast = data[2]; // ✗ magic number
   

   Without reading the whole block you can’t tell what 2 means. Introduce a named constant instead.
3. Cap a single method at ~60 lines. Separate the “highlight” logic from supporting details—extract helper methods for the green leaves so the red flower (the core logic) stands out.
4. Be careful with commented-out code. Either explain why it’s temporary or delete it. Version control lets you recover old logic; if you must comment something temporarily, leave a reason.
5. Avoid monolithic constants or util classes. Organize by business meaning so others can locate values quickly.

Plenty more rules exist—experience will tell you which ones matter most in your projects.

Final Thoughts

Software evolves constantly; methodologies endure. Enforcing conventions creates predictability and helps teams adapt. Put the manual into practice—it pays off.