Clarity of intent makes code’s purpose, expected behavior, and reason for existing unmistakable. It goes beyond showing what instructions do: the code should reveal the problem being solved and how its parts contribute. Clear intent begins with clear data, because data gives software behavior its meaning. section 4.0
Make the essential domain model visible. Generic objects and unexplained primitive values can hide meaning; names and types that express the domain let the surrounding logic follow naturally. This favors a data-oriented design in which behavior aligns with explicit data rather than burying it behind boilerplate. section 4.0
Replace ambiguous values with domain meaning
`new User("John", 180, 70)` leaves readers to infer what the numbers mean. A `PhysicalProfile` with `WeightInPounds` and `HeightInInches` makes both the values and their units part of the code’s stated purpose. section 4.0
PhysicalProfile johnProfile = new PhysicalProfile(
"John",
new WeightInPounds(180),
new HeightInInches(70)
);
This representation turns unnamed numeric arguments into named domain concepts, making the modeled information apparent at the construction site. section 4.0
Intent is reinforced rather than achieved alone. Simplicity lowers cognitive complexity, expressiveness keeps code close to the problem, and narrative structure lets transformations read as a coherent story. Explicitly modeling absence can similarly replace defensive null-check plumbing with a clearer description of the data flow. section 1.2.2 section 5.3
Improve unclear intent deliberately, not recklessly:
- Investigate complexity that cannot be justified before changing it; inspect history and ask teammates rather than assuming the code is pointless. section 3.2.5
- Weigh automated-test coverage, dependencies, release timing, detectability of regressions, and the consequences of a defect before refactoring. section 3.2.5
- Avoid concision that requires excessive mental unpacking; a shorter construct is not clearer when readers lack the needed background knowledge. section 5.3
Clear intent improves comprehension, safe change, maintenance, and long-term durability. It also matters when using AI agents: generated code can mirror an unclear codebase, while working code that cannot be explained or safely evolved creates comprehension debt. section 1.3
