Modular Design Review Checklist

Use this checklist before implementation and during architecture critique.

Complexity Goal

• What total system complexity is reduced?
• Which future changes become localized?
• Whose cognitive load is reduced?
• Which implicit facts become obvious?
• What hidden coupling is removed?

Module Depth

• Does each module provide substantial functionality behind a small interface?
• Would callers be simpler because the module exists?
• Would removing the module remove a real abstraction or just a wrapper?
• Does any module mostly forward calls?
• Does the interface expose nearly every internal step?

Interface Quality

• Is the public surface minimal but sufficient?
• Are operations named by caller intent?
• Are inputs and outputs stable and meaningful?
• Are common cases direct?
• Are special cases isolated?
• Are errors actionable?
• Can callers use the interface without reading implementation code?

Information Hiding

• Are storage details hidden?
• Are framework and transport details hidden outside boundary code?
• Are vendor details hidden?
• Are retries, caching, transactions, pagination, and sequencing hidden where possible?
• Are domain invariants enforced in one place?
• Are callers prevented from depending on internal representation?

Leakage Smells

• Do names reveal implementation instead of intent?
• Do parameters include state the caller does not own?
• Do return values expose raw rows, DTOs, framework objects, status codes, or vendor objects?
• Must callers call methods in a fragile sequence?
• Are special cases duplicated across callers?
• Would changing a database, vendor, or protocol require edits in unrelated callers?

Layering

• Does each layer use a distinct abstraction?
• Are domain concepts insulated from infrastructure?
• Are boundary translations explicit and localized?
• Are adjacent layers repeating the same method names and data shapes?
• Are pass-through methods or variables crossing layers?

Split or Merge

• Do separated modules hide different decisions?
• Do they change for different reasons?
• Are they split merely by execution order?
• Would merging reduce caller-managed coordination?
• Would splitting reduce unrelated change pressure?

Errors and Special Cases

• Can any error be designed away?
• Can any special case become a default or normal case?
• Can validation be centralized?
• Can a domain concept replace a flag or raw status?
• Are exposed errors meaningful to the caller?

Documentation

• Is the interface contract written before implementation?
• Do comments document behavior, invariants, side effects, and assumptions?
• Are names consistent with the domain language?
• Is example usage included for non-obvious APIs?

Final Gate

Approve the design only if these answers are clear:

1. What complexity is reduced?
2. Which module is deepest?
3. What knowledge is hidden?
4. What is the smallest useful interface?
5. What alternatives were considered?
6. What leakage risks remain?
7. Are pass-throughs avoided?
8. Are layer abstractions distinct?
9. Are errors and special cases centralized or removed?
10. What future change becomes easier?