software-development-norms

Software Development Norms

Industrial-grade software engineering rules abstracted from the Alibaba Java Development Handbook (Huangshan Edition). Every principle is language-agnostic; each rule uses a single illustrative example instead of cross-language comparison.

Overview

The Alibaba Java Development Handbook is a benchmark for enterprise-grade coding standards in China. Its rules are rooted in engineering wisdom — not language-specific syntax. This skill distills those rules into universal principles and warns against common anti-patterns that appear across codebases.

When you write code in any language, load this skill to check your work against battle-tested norms.

When to Use

• Writing new code in any language and want to follow professional conventions
• Reviewing code for quality, readability, and robustness
• Onboarding onto a project and need to internalize its baseline quality bar
• Refactoring code and want to avoid introducing anti-patterns
• Deciding on naming, error handling, concurrency, or project structure conventions

Do NOT use for:

• Language-specific style guide enforcement (use language linters instead)
• Debating syntax preferences that have no engineering impact

---

1. Naming

1.1 No abbreviations that obscure meaning

Principle: Names must be self-documenting. Never abbreviate by dropping letters arbitrarily — the reader must understand the intent without guessing.

# Good
remaining_retry_count = 3
pull_code_from_remote_repository()

# Bad
rmng_rtry_cnt = 3
a = 3

Anti-pattern: AbsClass for AbstractClass, condi for condition. If you can't say it out loud without explaining the abbreviation, the name is wrong.

1.2 Consistent naming conventions per scope

Principle: Each scope (package/module, class/struct, method/function, constant, variable) follows a single convention within the project. Mixed conventions create cognitive load.

Project rule: Define one naming convention per scope and apply it consistently across the repository.