The simple version
Writing code that other people can understand takes significantly more effort than writing code that works. Most engineers are scheduled for the latter and left to figure out the former on their own time.
Why this looks like an ego problem but isn’t
The common story about unreadable code is that engineers are territorial. They write cryptic variable names and skip comments so they become indispensable. Job security through obscurity. There are engineers who do this deliberately, but they are a small minority. The vast majority of hard-to-read codebases got that way because the person writing the code was under pressure to ship, not to teach.
This matters because if you believe the ego story, your solution is cultural: hire less arrogant people, build a more collaborative team. If you believe the time story, your solution is structural: change what you measure and what you schedule.
The ego story is more satisfying but less useful.
What actually happens when an engineer writes code
Here is the honest sequence of events on most software teams. An engineer gets a ticket. The ticket describes what the code should do. There is a deadline, sometimes explicit, sometimes implied by a sprint cycle or a product manager who checks in twice a day. The engineer writes code that satisfies the ticket. They open a pull request. The pull request gets reviewed, usually by someone equally pressed for time, who checks that the logic is correct and the tests pass. The code ships.
At no point in that sequence did anyone ask whether a new engineer joining in six months could understand what was written. That question has no ticket. It has no deadline. It produces nothing you can demo.
This is not cynicism. It is just what happens when you only measure output.
The technical term for this accumulation is technical debt, and it compounds
Every time an engineer writes code that works but doesn’t explain itself, they are borrowing time from the future. The next person who touches that code, which might be the same engineer two years later, will spend extra time figuring out what it does before they can change it. That slowdown is the interest payment.
Ward Cunningham, one of the authors of the original Agile Manifesto, coined the phrase “technical debt” in 1992 specifically to describe this dynamic. He meant it as a useful metaphor for communicating tradeoffs to non-technical stakeholders: borrowing against the future is sometimes the right call, but you have to actually pay it back. What he did not anticipate was that most organizations would enthusiastically take on the debt and quietly drop the repayment plan.
The result is codebases where even experienced engineers move slowly. Not because the engineers are bad, but because every small shortcut taken under deadline pressure is now a small tax on everyone who follows.
Three concrete things that make code readable, and why they all cost time
If you want to understand why readable code is hard to prioritize, look at what it actually requires.
Naming things well. A variable called d takes two seconds to type. A variable called days_since_last_login takes eight seconds and requires the engineer to stop and think about what the thing actually represents. That pause is where clarity happens, and it is also exactly the kind of pause that feels unaffordable when you are three days behind on a sprint.
Writing comments that explain intent, not mechanics. Bad comments describe what the code does, which you can already read from the code. Good comments explain why the code does it this way instead of another way. Writing a good comment requires the engineer to articulate a decision they probably made instinctively, which is genuinely hard cognitive work.
Refactoring as you go. The first version of any solution is usually structured around how you figured out the problem, not around how someone else would learn it. Turning the first into the second is a whole additional pass. It is also the thing that gets cut when a deadline moves.
None of these things are secrets. Every experienced engineer knows them. The issue is that none of them show up in a sprint ticket, and very few engineering managers have found a way to make them visible as work.
What you can actually do about this
If you manage engineers, the most practical thing you can do is make readability a measurable part of code review. Not vague encouragement, but specific criteria: Can you follow the logic without asking the author? Do the names tell you what things are for? If the answer is no, the review is not done. This sounds simple and it is resisted everywhere because it slows reviews down in the short term. It is still the right call.
If you are an engineer, the most practical thing you can do is budget the second pass explicitly. Write the code that works. Then take twenty minutes to rename things and add the comments you wish you had found. Do not wait for a refactoring ticket that will never come. Treat the twenty minutes as part of writing the feature, because it is.
If you are a non-technical manager trying to understand why your codebase is slow and expensive to change, the explanation is almost certainly not that your engineers are bad at their jobs. It is that you have been scheduling them for output and measuring them on output, and readable code is not output in any way your current system can see.
The fix is to make it visible. Name it in reviews. Track it in retrospectives. Give engineers explicit time for it. That is not a soft cultural gesture. It is the most direct way to stop paying compound interest on decisions that were made under pressure years ago.
