CLARITY Framework

Pragmatic software design principles for maintainable, testable, and evolvable code across all tech stacks.

Personal Note: I came up with the CLARITY framework as my own extension of the classic SOLID principles. SOLID is still the foundation I rely on, but sometimes I needed extra guidance for testing, dependency management, and avoiding premature complexity. CLARITY is not meant to replace SOLID, it is simply my shorthand reminder from working alone on projects to keep the code maintainable and manageable.
C

Contracts, Not Guesses

Every unit has explicit input/output, errors, and timing guarantees. Write it down once; make all implementations live up to it.

L

Lifetimes & Injection

Dependencies must be explicit, injected, and scoped correctly. Object creation belongs in the composition root.

A

Adjust Safely

Bias toward adding new behavior when cheap/safe. When extensions pile up or duplicate logic emerges, refactor.

R

Replaceability

Swap any implementation behind an abstraction without client changes, different error shapes, or timing assumptions.

I

Interfaces Small

Split capabilities into focused interfaces. No "maybe" methods or kitchen-sink interfaces.

T

Tests as Spec

Tests define behavior and protect contracts. Run the same contract tests against all implementations.

Y

YAGNI Discipline

Don't add knobs, layers, or abstractions "just in case." Add complexity only when a real requirement appears.

Philosophy

Add first if it keeps stability and helps learning.
Refactor when the third similar piece shows up or when replaceability breaks.
Guard everything with contracts and tests.

The CLARITY framework is not about chasing perfection. It is just a set of reminders I use to make pragmatic choices so the codebase stays maintainable and can keep evolving. Start simple, add complexity only when it is really needed, and always protect contracts with tests.