Java API Design Checklist and Guidelines

This checklist serves as a reference for Java API designers, analogous to a pilot's pre‑flight checklist, ensuring thorough consideration of design specifications.

Package checklist includes recommendations such as separating API and implementation into different packages, placing API in higher‑level packages, avoiding internal dependencies between API implementation classes, and not over‑fragmenting packages.

Naming checklist advises using company root namespace for top‑level packages, stable product names for sub‑packages, avoiding mixed case, avoiding “api” in package names, and using PascalCase for types with appropriate suffixes like “Exception” or “Abstract”.

Documentation checklist stresses providing a package.html, following Javadoc conventions, summarizing the API, detailing usage, marking entry points, including examples, links to guides, version numbers, @deprecated tags, and avoiding excessive length.

Type design checklist covers common principles (single purpose, domain relevance, limit number and size, consistency), naming (noun phrases, PascalCase, avoid abbreviations), class design (minimize dependencies, list public methods first, avoid deep inheritance, prefer abstract classes, use enums, generics, interfaces, and immutability), interface design (provide implementation, avoid marker interfaces), enum design (provide a NONE value, avoid single‑value enums), and exception design (serializable, specific per type, avoid deep hierarchy, no sensitive info).

Method design checklist includes common rules (single purpose, consistent granularity, atomic calls), naming (expressive verbs, PascalCase, avoid generic verbs), parameters (choose appropriate types, handle null consistently, order inputs before outputs, prefer collections over arrays, avoid boolean parameters, avoid exposing implementation details), exception handling (throw only on error conditions, use standard Java exceptions, check preconditions), overriding (use @Override, maintain or weaken preconditions, strengthen postconditions), constructors (keep work minimal, provide sensible defaults, validate parameters, consider builders or static factories), getters/setters (use get/is/set prefixes, validate setters, minimize work, return immutable collections, avoid returning arrays), callbacks (strict preconditions, weak postconditions, place callback as first argument, avoid return values), and documentation (Javadoc for each method, short summary, @deprecated, usage examples, performance notes, remote calls, external resources, unit tests).

Overall, the checklist helps identify design flaws, improve API quality, and decide when to refactor.