Do Son 
Picture a service written in impeccably clean style: clear names, neat decomposition, tests in place. Then suddenly — a strange spot: a forked third-party library for handling a specific protocol. A public version exists, but the team keeps its own, with modifications. Why? What exactly did the original fail to support? In the commit history, the author left the company two years ago, and the task says only “implement protocol support.” The code shows flawlessly how it works. Why it was done this way, no living person knows.
For most IT teams this is a familiar situation. For an engineer with experience in large platforms it is also an alarming one: a spot that no one fully understands is the place where, someday, either the service itself or an attempt to change it safely will break.
Oleksandr Zhartovskyi, a distributed-systems engineer, believes that the modern cult of clean code solved one problem and masked another. Here is what he means.
Where clean code ends
Zhartovskyi does not argue with the classics. In Clean Code, Robert Martin writes that the code is the ultimate source of truth, that documentation goes stale, and that the best documentation is the code itself, written so that it needs no explanation. Zhartovskyi mostly agrees — with one caveat.
“Self-documenting code closes off a huge amount of pain: onboarding, maintainability, readability,” he agrees. “If code needs comments to be understood, to me that’s a signal that the naming or decomposition went wrong. About ninety-five percent of code can be written so that comments become unnecessary.”
The problem is that code answers only the question of “how.” It shows precisely how the system works today, but says nothing about why it was made this way. Picture a new engineer who comes across a strange piece of code. He understands every line but doesn’t know the main thing — why it was done this way. It could have been a hastily placed crutch that should have been removed long ago. Or it could have been a deliberate decision, without which the system would run slowly. From the outside, you can’t tell one from the other. Remove it, thinking it’s a crutch, and you bring the system down. Be afraid to touch it, and you carry a questionable solution forward. The team has the code but no map: it knows where it stands and doesn’t know where it’s safe to step next.
What gets lost
The “why,” Zhartovskyi says, comes in different kinds, and he breaks it into three levels. Technical — why a particular tool was chosen: for example, the platform uses a certain message broker because of latency requirements that were relevant a year ago, but the team no longer remembers the details of that decision. Business — why the logic is arranged a certain way: say, the billing algorithm counts payment through a specific entry point because of a partner agreement whose term expired long ago, while the structure remained. Historical: why a workaround sits here that no one dares to touch.
The first two can still be recovered. The technical “why” an experienced engineer will eventually reverse-engineer from the code itself. The business one can be glimpsed in how other systems in the same industry are built. But the historical “why” cannot be recovered from anywhere.
“It’s unique not even to the product, but to a specific team at a specific moment,” Zhartovskyi explains. “As in, we decided it that way back then because there were circumstances that existed only then. The circumstances are gone, and the decision remained. And no one knows anymore whether it can be touched, or whether it holds up something critical.”
The worst part is that such an invisible dependency breaks at any scale: from a forked library for a single encoding, to a synchronous link between two particular services, to the overall architecture of the entire platform.
Zhartovskyi recalls a telling case. On one project there was a single systems analyst who kept the entire context in his head. He wrote documentation, but it didn’t explain even half the decisions. Some things were done simply because “he said so.” He handed developers large chunks of business logic as ready-made scripts, and when asked to explain the details, he replied that it would take too long.
“One day he left. And what formed was not a vacancy but a vacuum,” Zhartovskyi says. “It took several specialists to replace one role. The team dropped out of quality development for months: it moved by inertia, closed current tasks, but everything fundamental came to a halt until our own people grew into it. You can’t hire such people on the market; you grow them in-house.”
Knowledge that lives only in the head of one or two people is a single point of failure. A system with such a point is doubly vulnerable: it stops when the person leaves, and it becomes dangerous when, under the pressure of an incident, someone touches a spot whose purpose no one remembers anymore.
A minimal map
A perfect documentation system, according to Zhartovskyi, does not exist, and chasing it is pointless. Instead, there is a minimum that any team can put in place as early as tomorrow — the task ID in the commit description.
The chain is simple. In the editor you can see who changed a line and when. By the commit hash you find its description, in the description — the task number, and the task itself leads to the tracker, where the discussion and the agreed decisions remain. On this point Zhartovskyi is categorical: it is the only one hundred percent reliable way to preserve context, because it is tied to the code for good.
“But the chain works only if the task isn’t empty,” he stresses. “It has to record why it was done this way, which alternatives were weighed, what was decided at review. Work by the ‘got a task, did it, closed it’ pattern leaves nothing behind but code, which again will tell you only the ‘how.’”
If a company moves to a new tracker, the old tasks must be migrated or at least kept as an archive. Breaking the “commit — task” chain turns all the accumulated context into archaeology without artifacts.
For decisions more serious than an ordinary task, there is the next level — an analytical document before development begins. “First the document, then the code, not the other way around,” Zhartovskyi clarifies. “When the document precedes the work, the documentation gets written almost always, because it’s a precondition. When it’s the reverse, the two processes never sync up.”
Culture, not an artifact
The right sequence — first the document, then the code — removes, by Zhartovskyi’s estimate, about eighty percent of documentation problems. The remaining twenty are the decisions made during the work itself: these have to be watched over by a manager — not to force, but to remind. The counterargument that documentation goes stale and becomes misleading, he rejects: even outdated context is more useful than emptiness, because it can be checked against the code, whereas emptiness has nothing to check against.
But Zhartovskyi answered the “knowledge in people’s heads” problem most convincingly not with words but with a concrete tool. He built from scratch a training program for new developers in his department — before him, onboarding at the company rested on verbal explanations, with no materials or structure. He put one idea at its core: the trainee builds, with their own hands, a simplified but working copy of the production platform — on the same technologies and patterns as the real one.
“When a person has built a small version of the system themselves, they come into production and already recognize the architecture, the tools, the data flows,” he explains. “The transition from training to real work becomes seamless.”
The training program became the main onboarding path for new developers in Zhartovskyi’s department. He developed this model in Ukraine, and now shares it with engineering teams in the United States.
Maps are needed because people leave
Clean code was and remains mandatory — without it, a complex system can’t be held together. But on its own it protects a team only as long as the same people who wrote it are still there. The moment they leave, half the system — the half that’s in no file — leaves with them. A map — context recorded in tasks, documents, training — is what remains when the people are already gone. It turns the system from an asset that rests on the memory of a few engineers into an asset owned by the whole team.
For a business this is a question of resilience, not of code tidiness. A company that keeps key knowledge in a few heads lives on borrowed time — right up until the first resignation at a bad moment.
“Maps aren’t needed because the code is bad,” Zhartovskyi sums up. “Maps are needed because people leave. And the system remains — and someone has to understand why it’s the way it is before touching it.”