expression-clarify

name

expression-clarify

description

Make code more expressive so logic and intent are self-evident through naming, structure, flow, and locality. Use when: (1) asked to prepare code for review where implementation requires translation effort to understand, (2) explanations require translating from implementation details to meaning like "this variable represents...", (3) function names describe mechanics rather than purpose or comments explain what code does rather than why, (4) choosing between working implementations based on which will be clearest to future readers.

Clarify

Make code speak its own intent through structure and naming, so readers grasp what it does and why it matters without translating from implementation details.

Instructions

When I encounter code that requires mental translation to understand, I apply transformations that reveal intent directly through the code's expression.

1. Reveal purpose through naming - I examine every identifier to see whether it answers "what role does this play in the problem domain?" rather than "what type is this?" or "what operation does this perform?", replacing names like data, temp, result, process, or handler with names that capture business meaning, because generic names force readers to reverse-engineer intent from context while domain names make intent immediate.

2. Structure for comprehension - I organize code to mirror the logical flow of the problem it solves rather than optimizing for execution mechanics, grouping related operations together even if they use different language features, separating concerns that serve different purposes even if they execute sequentially, and ordering operations so readers can follow the narrative of what's being accomplished without jumping between distant locations.

3. Make control flow visible - I examine conditional logic to see whether its structure reveals the decision-making clearly or obscures it through nesting and inversion, using guard clauses to make preconditions explicit rather than burying them in else branches, extracting complex conditions into named predicates that explain what's being tested rather than how it's calculated, and choosing between early returns, pattern matching, or explicit branches based on which makes the decision structure most apparent.

4. Minimize distance between definition and use - I look for places where understanding a piece of code requires remembering context from far away, moving variable declarations closer to where they're used, extracting related logic into cohesive units so readers don't hold state in working memory, and inlining single-use abstractions that add indirection without adding meaning, because locality of reference reduces cognitive load.

5. Choose extraction over inline based on comprehension - I evaluate whether extracting code into a named function aids understanding by giving a meaningful name to a concept versus whether it obscures understanding by forcing readers to jump to another location, extracting when the name of the extracted function communicates more clearly than reading its implementation, but keeping code inline when the extraction only adds ceremony without adding clarity.

6. Replace implicit with explicit - I identify places where the code relies on implicit assumptions, hidden state, or contextual knowledge that exists only in developers' heads, making these explicit through names, types, or structure that encode the assumption directly in the code, because what's implicit requires shared context to understand while what's explicit carries its own context.

7. Reduce translation tax - I notice when understanding code requires mentally converting from low-level operations to high-level concepts, and I rewrite to operate at the level of those high-level concepts directly, using domain vocabulary in code structure so readers work with business ideas rather than translating from arrays, loops, and conditionals into meaning.

Examples

From generic variables to domain roles

I'm reviewing a function that calculates shipping costs. It has variables named x, y, and z for three numeric inputs, temp for an intermediate calculation, and result for the final value. Reading through the logic, I discover that x is the package weight, y is the distance to destination, z is a rush delivery flag encoded as 0 or 1, temp holds the base cost before applying surcharges, and result is the final price with all fees included. Every time I read this function, I have to rebuild this mental map between generic names and their domain meaning. I rename these to packageWeightKg, distanceKm, isRushDelivery, baseCostBeforeSurcharges, and finalPriceWithFees. Now the function reads like a description of the business logic rather than a math problem. The calculation temp = (x * 0.5) + (y * 0.1) becomes baseCostBeforeSurcharges = (packageWeightKg * costPerKg) + (distanceKm * costPerKm), revealing that the magic numbers are cost rates rather than arbitrary constants. The cognitive benefit is immediate: readers understand what the function does without first decoding a mapping between variables and concepts.

From nested conditionals to readable requirements

I'm examining error handling code that has five levels of nested if-else statements checking various conditions before proceeding with an operation. The structure is: if the user exists, then if they're verified, then if they have permission, then if the resource is available, then if quota allows, then proceed, else throw quota error, else throw availability error, else throw permission error, else throw verification error, else throw existence error. Each error is buried in an else clause at its corresponding nesting level, making it difficult to see what preconditions must be satisfied. I restructure this using guard clauses that read like a list of requirements: check if user doesn't exist and throw immediately, check if user isn't verified and throw immediately, check if user lacks permission and throw immediately, check if resource isn't available and throw immediately, check if quota exceeded and throw immediately, then proceed with the main operation. Now the preconditions are visible at a glance, each expressed positively as a requirement that must be met. The structure mirrors how I would describe the requirements in conversation: "First the user must exist, then they must be verified, then they must have permission..." The cognitive benefit is that the shape of the code matches the shape of the problem domain rather than the mechanical structure of if-else nesting.

From imperative mechanics to declarative intent

I'm reviewing code that processes a list of orders to find those that are ready to ship. The implementation uses a for loop iterating through the orders array, maintaining a counter variable, using multiple nested if statements to check order status, inventory availability, and payment completion, pushing matching orders into a results array, and tracking statistics about how many were excluded for each reason. Reading this requires mentally simulating the loop execution to understand what's being calculated. The intent is buried in the mechanics of iteration and accumulation. I rewrite this to work at a higher level: filter the orders to those where status is processed, inventory is available, and payment is complete, then map to add shipping labels, then count the total. The transformation from imperative to declarative eliminates the loop variable, the accumulator, and the explicit iteration, replacing them with operations that name their intent: filter, map, count. Now I can read what the code accomplishes rather than simulating how it executes. The imperative version required understanding mechanism to infer intent, while the declarative version states intent directly. The cognitive benefit is working with business concepts rather than programming constructs.