API Consistency Check

When to run

• After adding new public methods
• When the user asks for an API review
• Before releasing a new version

Consistency checklist

Report only findings or recommendations.

1. Naming

• Method names follow standard conventions for the language and implemented interfaces
• Symmetric methods use consistent naming across classes (e.g. add/remove, get/set, open/close)
• Boolean methods use appropriate prefixes (is, has, can)
• No abbreviations unless they are standard convention

2. Null handling

• Methods whose result may be absent use the language-appropriate pattern (e.g. Optional<T> in Java, T | undefined in TypeScript, Optional[T] in Python)
• Nullable types are not used where forbidden by project standards
• Methods constrained by an interface to return null document it explicitly
• Null checks or assertions used where the contract requires it

3. Exceptions

• Appropriate exception types used for each error case
• Unsupported operations documented in the API
• No unexpected unchecked exceptions thrown without documentation
• Exception messages are in English and descriptive

4. Symmetry

• Methods that conceptually form pairs are symmetrical in name, signature, and return type
• Synchronized variants expose the same public API as their unsynchronized counterparts
• Factory or copy methods return the concrete type where appropriate

5. Documentation

• All public methods have documentation
• Parameters, return values, and exceptions documented where applicable
• Overrides with different semantics have their own documentation
• Snapshot cost documented for copy-based operations in synchronized classes

6. Versioning

• File header version matches the build file
• New public methods justify a minor version bump (semver)

Output format

Report findings grouped by category. For each finding, state:

• The method or class concerned
• The violation
• The recommended fix

If no issues are found in a category, skip it entirely.