Contact us

The Problem With “John”: The Developer Who Built Everything but Documented Nothing

by Eric Hanson, Backend Developer at Clean Systems Consulting

Every team has a “John”—the brilliant developer whose output seems unstoppable.
Features roll out, production stays stable, and managers see him as indispensable.

But there’s a hidden cost: the rest of the team struggles to understand, modify, or safely extend his code.

Code Should Be Living Documentation

Documentation isn’t just a separate Word file or PDF.

  • Well-written code explains itself in clear naming, structure, and comments
  • High-level architecture embedded in the code helps others understand design decisions
  • Tests, examples, and readable functions are part of “living documentation”

When John writes code that only he can decipher, the system becomes a trap rather than a guide.

The Paradox of Perceived Value

Because John produces so much, he looks good in the manager’s eyes.

  • rapid delivery impresses stakeholders
  • managers may overlook maintainability issues
  • “John is busy, don’t disturb him” becomes team lore

Meanwhile, other developers hesitate to touch his codebase—any mistake feels high-risk.

Invisible Bottlenecks

John unintentionally creates obstacles for team productivity.

  • peer developers avoid areas of the code he owns
  • onboarding new hires becomes painful and slow
  • dependencies and tight coupling make seemingly simple changes risky

What appears as heroism to outsiders is a hidden drag on velocity for the team.

Encouraging a Culture of Readable, Maintainable Code

Teams can mitigate these issues without stifling creativity.

  • enforce clear naming conventions and code readability
  • encourage self-explaining functions and thoughtful structure
  • code reviews and pair programming distribute knowledge, not hero worship

The goal is living documentation that communicates through the code itself, not through extra files.

Balancing Individual Brilliance and Team Flow

John’s contributions are valuable—but only if they help the team, not just impress managers.

  • celebrate output while prioritizing clarity and maintainability
  • teach that code is communication, not a personal trophy
  • empower others to safely work on any part of the system

Brilliance that isolates is fragile; brilliance that educates is sustainable.

John may deliver miracles, but the real measure of a team’s health is whether everyone can safely build on each other’s work.

Code should speak in plain English, not just to the genius who wrote it.

Scale Your Backend - Need an Experienced Backend Developer?

We provide backend engineers who join your team as contractors to help build, improve, and scale your backend systems.

We focus on clean backend design, clear documentation, and systems that remain reliable as products grow. Our goal is to strengthen your team and deliver backend systems that are easy to operate and maintain.

We work from our own development environments and support teams across US, EU, and APAC timezones. Our workflow emphasizes documentation and asynchronous collaboration to keep development efficient and focused.

  • Production Backend Experience. Experience building and maintaining backend systems, APIs, and databases used in production.
  • Scalable Architecture. Design backend systems that stay reliable as your product and traffic grow.
  • Contractor Friendly. Flexible engagement for short projects, long-term support, or extra help during releases.
  • Focus on Backend Reliability. Improve API performance, database stability, and overall backend reliability.
  • Documentation-Driven Development. Development guided by clear documentation so teams stay aligned and work efficiently.
  • Domain-Driven Design. Design backend systems around real business processes and product needs.

Tell us about your project

Say Hej

Our offices

  • Copenhagen
    1 Carlsberg Gate
    1260, København, Denmark
  • Magelang
    12 Jalan Bligo
    56485, Magelang, Indonesia

More articles

The Research Triangle Produces Top Backend Talent That Startups Rarely Get to Hire

NC State, Duke, and UNC feed one of the strongest engineering pipelines in the Southeast. Most of it flows somewhere other than your startup.

Read more

5 Signs Your Startup Is Ready to Hire a Remote Backend Contractor

Not every startup is set up for async remote contracting. Here's how to tell if yours is — before you find out the hard way mid-engagement.

Read more

Spring Boot API Documentation With OpenAPI — Generating, Hosting, and Keeping It Accurate

API documentation that drifts from the implementation is worse than no documentation — it misleads integrators and wastes time. Here is how to generate accurate OpenAPI specs from Spring Boot code, keep them in sync, and host them effectively.

Read more

What a Spring Controller Should and Shouldn't Do — A Practical Boundary Guide

Spring controllers accumulate logic because they're the most visible layer and the easiest place to add code. The result is controllers that are hard to test, hard to reuse, and hard to change. Here is a clear boundary that scales.

Read more