Diagnosing Software Complexity Through the Cost of a Change
“Add a fourteen-day option” sounds like a small request. On the settings page, it is: one more item in a dropdown.
Now put that request in a file-sharing application. A workspace administrator chooses how long files remain before an automatic cleanup process removes them. The application currently supports seven or thirty days. Adding fourteen days means making a promise about deletion, not just displaying a new label.
Follow an engineer through this illustrative change. They update the dropdown, then discover a request validator with its own list of accepted values. The settings summary has another interpretation. A background worker contains a fourth: anything other than seven means thirty.
The form can display fourteen days while the worker still keeps files for thirty. Everything the engineer thought to check might work. The missing piece is knowing what else to check.
That is a useful way to make software complexity concrete. A codebase becomes difficult to change when an ordinary request requires repeated edits, a large amount of remembered context, or knowledge the code gives you little reason to discover. Short functions and a small diff can coexist with all three problems.
This article follows the retention setting through a small TypeScript example. By the end, you will be able to distinguish those three symptoms, trace the behavior behind a UI change, and bring specific evidence to a design review before choosing a refactoring.
On this page
Use a Real Change as the Unit of Analysis
A large application can be straightforward to modify in a particular area. A small application can require its maintainer to remember several invisible rules before changing one field.
Opening the repository and counting classes will not tell the engineer whether the new retention option is safe to ship. Start with what the administrator should be able to rely on.
For the retention example, that outcome could be:
A workspace administrator can select fourteen-day retention. The server accepts it, the settings page displays it accurately, and the cleanup process uses that duration.
This description gives us several behaviors to follow. It also keeps the investigation grounded: we are examining the cost of one supported setting, not reviewing every architectural choice in the application.
Before following the code, write down where you expect that behavior to live. Compare that expectation with what you actually discover. The difference captures the surprising part of the work, which is easy to forget once you know the system.
Three Different Symptoms Can Hide Behind “This Is Complicated”
As the engineer follows the setting, three different problems emerge. They need different responses, even when all three get described in a review as “this area is complicated.”
Change Amplification: One Decision Requires Repeated Edits
The first problem appears before the worker enters the picture. The application repeats its list of supported retention periods:
type RetentionDays = 7 | 30
type WorkspaceSettings = {
retentionDays: RetentionDays
}
const retentionOptions: Array<{
value: RetentionDays
label: string
}> = [
{ value: 7, label: 'Seven days' },
{ value: 30, label: 'Thirty days' },
]
function parseRetentionDays(value: unknown): RetentionDays {
if (value === 7 || value === 30) return value
throw new Error('Unsupported retention period')
}
function retentionSummary(days: RetentionDays): string {
return days === 7 ? 'Retained for seven days' : 'Retained for thirty days'
}
Adding 14 to the type does not add an option, change validation, or correct the summary. Those edits belong to the same product decision, yet each must be made separately.
Multiple edits are not automatically evidence of bad design. A new capability may legitimately require a server implementation, a UI control, documentation, and tests. The diagnostic question is narrower: which locations independently encode the same decision?
The retention type, option list, validator, and summary each know which values exist. Keeping that knowledge consistent requires coordination. That repeated coordination is the amplification we want to recognize.
Counting modified files alone would obscure the distinction. Four files with independent responsibilities can be easier to change than one file with four subtly different copies of a rule.
Cognitive Load: The Diff Is Small, but the Required Knowledge Is Large
The engineer fixes those lists, then opens the cleanup task:
function cleanupCutoff(settings: WorkspaceSettings, now: Date): Date {
const effectiveDays = settings.retentionDays === 7 ? 7 : 30
const millisecondsPerDay = 24 * 60 * 60 * 1000
return new Date(now.getTime() - effectiveDays * millisecondsPerDay)
}
After the type is extended to include fourteen days, this function still compiles. Its conditional has a valid branch for every input, but that branch implements the wrong policy for the new value.
An engineer changing the setting must now know that cleanup contains its own interpretation. They must also understand whether a “day” means a fixed twenty-four-hour duration, as it does in this example, or a calendar boundary in a particular time zone. They need to establish whether existing records are re-evaluated immediately or only when cleanup next runs.
The product has to answer those questions somewhere. Centralizing a list will not decide whether deletion happens at a calendar boundary or on the next worker run. The design problem is how an engineer discovers the answers and which ones they must keep in mind while editing another part of the system.
A three-line patch can therefore carry substantial cognitive load. The visible code does not show the time spent searching, reconstructing assumptions, checking other consumers, or asking someone how the worker is deployed.
A useful review question is: what facts must an unfamiliar maintainer know to make this change correctly, and where would they find each fact?
Unknown Unknowns: The Engineer Does Not Know What to Look For
Change the story slightly: the engineer finds the type, options, validator, and summary but never discovers the cleanup task. They submit a plausible patch. The reviewer follows the same visible path. The settings page accepts fourteen days and displays it correctly.
The worker still uses thirty.
This failure is harder to prevent than a long, visible checklist of edits. A checklist tells you what work remains. Here, the missing relationship makes a partial change look complete.
This is what makes unknown unknowns especially dangerous. The developer lacks both the information and a reliable indication that the information is missing.
The term describes the engineer's position before discovery. Once a failing test reveals the cleanup assumption, it becomes a known problem. The useful next question is why the relevant behavior was hard to discover and how the next maintainer could encounter it earlier.
Trace the Setting Across Its Whole Lifetime
A frontend control is often the easiest entry point, but a setting has a longer life than its form field. Follow it through acceptance, persistence, reading, background use, and presentation.
For the illustrative retention change, a trace might look like this:
| Location | Knowledge required | Diagnostic question |
|---|---|---|
| Settings control | Permitted choices and display labels | Is this another independent list of supported values? |
| Request validator | Which submitted values are accepted | Can it drift from the UI and persisted representation? |
| Settings summary | Meaning presented to the administrator | Does it assume there are only two cases? |
| Cleanup task | Actual deletion cutoff | Where does it get the retention policy? |
| Fixture generator | Representative persisted settings | Would it ever exercise the new value? |
This table is an investigation aid, not a proposal to combine all five locations. Their responsibilities may remain separate. Its purpose is to reveal repeated knowledge, implicit assumptions, and gaps in discoverability before choosing a redesign.
Follow each edge with a specific question. Does the worker read the stored setting directly? Does another service transform it? Can old values remain after a deployment? Is the administrator selecting a preference or a guarantee about when deletion occurs?
These questions often reveal that the difficult part of a settings change is its contract across time and processes, rather than the component rendering its options.
Dependencies and Obscurity Explain the Symptoms
The worker's conditional explains why this change is troublesome better than a count of files does. It depends on the allowed values, but that dependency is expressed as an assumption about everything that is not seven.
A dependency exists when understanding or changing one piece requires considering another. In the example, validation and cleanup depend on the meaning of retention days. That relationship is unavoidable: a useful cleanup process must honor the configured policy.
The trouble comes from how the relationship is expressed. A worker that quietly translates every non-seven value to thirty has a dependency on the set of permitted values without referring to that set. The type checker cannot establish that its interpretation is semantically complete.
Obscurity concerns information that is difficult to see. An unexplained fallback, an undocumented unit, a fixture that omits an important case, or a separate process absent from the feature documentation can all make the correct change harder to infer.
The aim is therefore not to eliminate every dependency. A shared definition also creates dependencies: its consumers must understand and follow it. The useful comparison is whether those dependencies become simpler, more explicit, and easier to check.
This distinction prevents an unhelpful response to every difficult change: adding another abstraction immediately. First establish what knowledge is coupled, what information is hidden, and which obligation is being repeated. The suitable design response depends on that diagnosis.
Collect Evidence Without Turning It Into a Score
A short change record can make a design discussion more precise:
- Expected work: add a permitted value and expose it to administrators.
- Actual work: edit four definitions and one cleanup assumption; update representative fixtures.
- Required knowledge: retention units, validation rules, persisted values, and cleanup timing.
- Unexpected discovery: the worker treats all non-seven values as thirty days.
- Consequence of omission: the application displays one policy while deletion follows another.
These are observations about the example, not measured productivity data. A team can collect equivalent evidence from actual changes without inventing a complexity index.
Avoid ranking modules by file count or time spent in isolation. Investigation time may reflect unfamiliarity, missing access, or an unusually demanding requirement. Comparing several changes through the same area is more informative than treating one slow task as proof of architectural failure.
Also consider how frequently a difficult area affects development. Complexity behind a stable boundary has a different practical impact from complexity that every routine feature exposes. Use that distinction to prioritize investigation; it is not a precise numerical model for estimating delivery dates.
Small Exceptions Accumulate Into a Working Environment
The retention example can emerge through individually understandable decisions. A two-option summary uses a conditional. A worker copies the same conditional. A test fixture chooses the most common value. A later change adds a third option to the visible form.
None of those steps needs to look dramatic in a pull request. Their combined effect is an environment in which maintainers must reconstruct more relationships before making an ordinary change.
This incremental accumulation explains why “we will clean it up when it becomes a problem” is difficult to apply. The cost arrives through many small obligations, and removing one does not instantly make the rest disappear.
Reviewing only whether the new branch works misses that accumulation. Also ask what the branch makes future changes require: another synchronized edit, another special case, or another fact held only in someone's memory.
Bring a Change Trace to the Design Review
Return to the original request. The engineer should not declare the fourteen-day option finished when the form works. The acceptance path must reach the deletion cutoff, and a case exercising fourteen days must expose the worker's old assumption. That is a concrete decision the investigation supports before anyone proposes a new architecture.
For your own next change, write down the intended behavior, trace its consumers, and record the assumptions you discover. Ask another engineer to follow the same path without your explanation. Their uncertainty can reveal information that familiarity has made invisible to you.
Then distinguish the symptoms:
- Are you repeating one decision in multiple locations?
- Are you carrying too many facts to modify the behavior safely?
- Is there important work that the code gives you little reason to discover?
Use the answers to choose the next step. Repeated policy definitions need a clear owner. Necessary behavioral rules need a discoverable contract. A hidden worker needs an explicit connection to the feature's acceptance path. Those are different improvements, and each can be reviewed against the change that revealed it.
The useful result is an administrator whose chosen policy matches the worker's behavior, and a next maintainer who can establish that match without rediscovering the whole system.
