Software Design Complexity Review

Goal

Find the design choices that make code harder to understand or change, then recommend the smallest improvement that reduces total complexity.

Review Pass

Check for:

• Change amplification: one concept requires edits in many places.
• Cognitive load: readers must remember too much hidden context.
• Unknown unknowns: important behavior is not discoverable from names, interfaces, tests, or comments.
• Obscurity: intent is buried in incidental mechanics.
• Special cases: callers must handle avoidable exceptions or mode flags.
• Shallow abstractions: thin wrappers that add names without hiding complexity.
• Pass-through plumbing: methods or variables relayed through layers without adding meaning.
• Temporal coupling: callers must know the order of operations.