DEV Community: Dario Cuevas

🎃 10 Spooky Engineering Antipatterns That Haunt Your Codebase (And How to Exorcise Them)

Dario Cuevas — Fri, 31 Oct 2025 12:17:40 +0000

🎃 10 Spooky Engineering Antipatterns That Haunt Your Codebase (And How to Exorcise Them)

👻 When Fear Takes Control

Let me be honest with you from the start—this isn't going to be one of those perfectly academic blog posts filled with textbook definitions and pristine case studies. This is real talk about real engineering nightmares I've lived through, and I'm willing to bet you've experienced many of them too.

Here's the terrifying truth: when deadlines loom and fear creeps in, we all commit similar antipatterns. It doesn't matter if you're a junior engineer or a seasoned tech lead—fear blocks our rational thinking. That looming sprint deadline, that critical production release, that executive breathing down your neck—they all trigger the same response: shortcuts, compromises, and decisions we know we'll regret later.

I've seen it countless times in standups, retrospectives, and 2 AM Teams messages. We become predictable in our panic. We skip the tests "just this once." We hard-code that value "temporarily." We tell ourselves we'll fix it later, knowing deep down that "later" rarely comes.

This Halloween, I want to shine a light on these ghosts haunting our codebases and our processes. Some of these antipatterns are well-documented in books like Clean Code by Robert C. Martin. Others are more orthodox observations from the trenches—patterns I've noticed when fear takes the wheel and rational engineering takes the backseat.

So grab your garlic and wooden stakes. Let's hunt some monsters.

🕷️ Technical & Coding Horrors

1. The Ghost of Bad Comments (or Worse—No Comments)

You know what's scarier than no comments? Misleading comments that lie. Comments outdated three refactorings ago that nobody bothered to update.

Good comments explain the "why," not the "what." Your code should be self-explanatory. Comments should provide context, explain business logic, or warn about gotchas—not describe what the code does.

The exorcism: Make code readable without comments, but use them strategically to explain intent, constraints, and non-obvious decisions.

2. "I Finished—Only Tests Are Missing"

If tests are missing, you haven't finished. Period.

TDD isn't just about having tests—it's about using them to think through the behaviors you're adding. Writing tests first forces you to consider the API, edge cases, and failure modes. Writing tests at the end? You're retrofitting tests onto code that wasn't designed to be testable.

The exorcism: Write tests as you develop, not after. Make "tests passing" part of your definition of done.

3. The Boy Scout Rule? Never Heard of Her

"Always leave the campground cleaner than you found it." But here's what actually happens: we see ugly code, add our own ugly code on top, and move on. "This isn't my problem" or "I don't have time."

The Boy Scout Rule isn't about heroic refactorings. It's about small, incremental improvements—renaming a confusing variable, extracting a complex method, fixing a minor bug.

The exorcism: Make it a team habit. Every PR should leave the codebase slightly better—even if it's just one variable rename.

4. Over-Engineering: The Curse of Complexity

"We need to make this flexible for future requirements!" Famous last words before building a framework when a simple function would do.

Over-engineering bloats the codebase and introduces unnecessary risk. The best code I've written is code I later deleted because the feature didn't need code at all—just a config change.

The exorcism: Always ask: "What's the simplest thing that could possibly work?" Build what you need today. Refactor tomorrow if requirements actually change.

5. "The AI Generated This, So It's Probably Fine"

AI coding assistants are incredible. I use them daily. But "vibe coding"—pasting AI-generated code without understanding it—is how amateur programmers work, not professionals.

Treat AI as a pair programmer, not a replacement. Read every line it generates. Often, AI gives you something that works but isn't optimal for your context.

The exorcism: Always review, understand, and validate AI-generated code. You're responsible for every line that ships, regardless of who (or what) wrote it.

🧟 Behavioral, Process & Collaboration Nightmares

1. Forgetting Operational Readiness: The 2 AM Phone Call Horror

You ship the feature. Everyone celebrates. Then at 2 AM, production breaks, and nobody knows what to do.

Where's the observability? Where are the monitoring dashboards, the alerts, the runbooks or SOPs documenting how to handle incidents? When you ship without proper observability, you're saying: "Someone else will deal with it when it breaks."

The exorcism: Before production deployment, ensure monitoring is set up, alerting is configured, dashboards provide visibility, and runbooks are prepared. Make operational readiness a prerequisite for "done."

2. Optimism Bias: "If That Happens, Something's Very Wrong"

"Well, if the network fails at that point, we have bigger problems."

Really? Networks fail. Services become unresponsive. External dependencies time out. These aren't edge cases—they're Tuesday.

The exorcism: Design for failure. Add timeouts. Implement circuit breakers. Handle errors gracefully. Test your failure modes.

3. Implementation Over Outcome: The Cache Trap

The team spends two weeks debating how to implement a caching layer. Which library? Redis or Memcached?

Meanwhile, nobody asks: "Do we actually need a cache, or could we solve the performance problem with database indexes?"

The exorcism: Always start with the outcome. What problem are we solving? What's the simplest solution? Stay solution-agnostic until you've explored the problem space.

4. Horizontal Slicing: The Integration Nightmare

You break down a feature "logically": one story for frontend, one for backend, one for database.

Wrong. This creates dependencies, delays integration, and prevents early validation. The frontend team waits for the API. The backend discovers a fundamental database issue—after the frontend is "done." Now you rebuild both.

The exorcism: Break stories vertically. Deliver thin slices across all layers. Get feedback early. Iterate.

5. Code Reviews as Gatekeeping, Not Coaching

Code reviews are one of the best opportunities to level up your team. Yet how often are they just rubber stamps or nitpicking sessions?

When a senior engineer reviews a junior's code, they have a choice: approve quickly and move on, or invest time in teaching better patterns. The second option takes longer, but it compounds over time.

The exorcism: Treat every code review as a coaching opportunity. Ask questions instead of making demands. Explain the reasoning behind suggestions. Build a culture where learning is more valued than being right.

💀 The Exorcism Guide—Banishing These Ghosts

We've identified the monsters. Now let's reflect on how to banish them from your codebase and your process.

Key Takeaways

Fear and deadlines push us toward these antipatterns. But awareness is the first step to breaking the cycle. When you feel that pressure mounting, when shortcuts start looking attractive—pause. Ask: "Am I about to create technical debt I'll regret?"

These antipatterns aren't character flaws. They're natural human responses to stress. The difference between struggling teams and thriving teams isn't that thriving teams never feel the pressure—it's that they've built habits and guardrails to prevent fear-driven decisions.

Remember: if we all follow simple rules like the Boy Scout Rule, we would see the end of the relentless deterioration of our software systems.

Share Your Horror Stories

Now it's your turn. What's the scariest antipattern you've encountered? Which ghost haunts your codebase? Have you seen any of these patterns in your own work?

Please share your engineering horror stories. Sometimes the best exorcism is knowing we're not alone in fighting these demons.

Happy Halloween! May your code be bug-free and your deployments haunt-free. 🎃👻

Sources & Further Reading:

My previous article on MCP and code comments
Clean Code and other works by Robert C. Martin
The Software Engineer's Guidebook by Gergely Orosz
User Story Mapping by Jeff Patton
Escaping the Build Trap by Melissa Perri
Software Testing Anti-patterns
The Boy Scout Rule
Vertical Slicing Guide
Production Readiness Checklist

Why I Changed My Mind About Code Comments

Dario Cuevas — Mon, 27 Oct 2025 16:31:36 +0000

Why I Changed My Mind About Code Comments

🎬 The Awakening — When Your Own Code Bites Back

I still remember the day in 2011 when I found a piece of particularly nasty code in our codebase. I checked git blame. It was me. A year earlier.

This moment crystallized everything I'd learned since leaving consultancy in 2010. In consulting, you write code and move on. Someone else's problem. But in a product company? That code is yours. You'll maintain it, extend it, and curse it at 2 AM when production goes down.

That's when a senior engineer handed me Clean Code by Robert C. Martin. I devoured it. The book promised redemption through better naming, formatting, testing, and refactoring.

At its heart was a radical idea: comments are failures. If your code needs comments, you've failed to make it self-documenting.

I became a fanatic.

🧹 The Clean Code Years — When Comments Became the Enemy

From 2010 to 2014, I practiced what Robert Martin preached with religious fervor: kill the comments.

Instead of writing // Calculate the total price including tax and discount, I'd extract a function called calculateFinalPriceWithTaxAndDiscount(). The function name became the comment.

When I needed to explain a complex algorithm, I'd split it into smaller, well-named functions: validateUserInput(), processPaymentTransaction(), sendConfirmationEmail(). Each name was documentation embedded in code.

I had a killer argument against comments: they get outdated. Comments that lie are worse than no comments. Let the code be the single source of truth.

My code became cleaner. Functions smaller. Variable names ridiculously long but descriptive. I felt like a craftsman who'd mastered the technique.

But there was a nagging feeling I couldn't shake...

💡 The Philosophy Shift — When Everything Changed

Then I read A Philosophy of Software Design by John Ousterhout. My world turned upside down again.

Ousterhout directly challenged Clean Code: "Comments do not represent failures. The information they provide is quite different from that provided by code, and this information can't be represented in code today."

Wait. What?

The key insight: Comments are fundamental to abstractions. Without comments, you can't hide complexity. If users must read the code to use a method, then there is no abstraction—all complexity is exposed.

Here's a real example of my evolution:

Before (Clean Code approach):

function calculateTimeRemaining(startDate, endDate, excludeWeekends, holidays) {
  // Function name tells WHAT, but not WHY
}

After (Philosophy of Software Design approach):

/**
 * Calculates business days remaining for project deadline.
 * 
 * We use business days because our SLA commitments to customers
 * are based on business days. Weekend exclusion handles our 24/5
 * support model. Holidays vary by region.
 */
function calculateTimeRemaining(startDate, endDate, excludeWeekends, holidays) {
  // Implementation...
}

The function name tells you what. The comment tells you why, the business context, and the assumptions. Both are essential.

Ousterhout demolished Martin's solution of extracting functions with longer names: "This results in names like isLeastRelevantMultipleOfNextLargerPrimeFactor. Even with all these words, names like this are cryptic and provide less information than a well-written comment."

I suddenly saw all those ridiculously long function names for what they were: a workaround to avoid writing one clear sentence.

The synthesis I reached: Robert Martin was right about 80% of things. Clean code, expressive naming, small functions—all essential. But comments aren't failures. Bad comments are failures.

My current practice:

Short, internal functions: Minimal comments. The code speaks.
Complex functions: Comments explain the why and business context.
Public APIs: Comments are mandatory. They define the abstraction.
Tricky workarounds: Comments are essential. They save hours of confusion.

🤖 The AI Era — Why Comments Matter More Than Ever

Now we're in 2025, and there's a new player: AI coding assistants.

I use Claude Code with a claude.md file in my projects. Here's what I discovered: good comments make AI dramatically more effective.

GitHub Copilot, Claude, and other AI assistants use comments as crucial context. They parse not just syntax but interpret comments to understand intent and generate better suggestions.

This changes everything. We're not just writing comments for humans—we're writing them for AI assistants that help us code faster.

And let's remember: code is read far more than it's written.

Robert Martin himself said it: "The ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code."

In my 15+ years, this rings absolutely true. I spend my days understanding code before changing it, fixing bugs, reviewing code, investigating incidents, and onboarding team members. We're not creating greenfield projects daily—we're maintaining, extending, and evolving existing systems. All of that requires reading code.

If code is read 10x more than it's written, making code easier to read has a 10x multiplier on productivity. Good comments make code dramatically easier to read.

📝 What Good Comments Look Like

• Explain the "Why," Not the "What" — Code shows what. Comments explain why, what business logic it serves, and what assumptions it makes.

• Capture What Code Cannot Express — Document context, constraints, trade-offs, and decisions invisible in code.

• Stay Close to the Code — Comments next to what they describe stay updated. Avoid distant documentation.

• Don't Duplicate the Code — If your comment restates the obvious (// increment counter), delete it.

• Document Edge Cases and Gotchas — Weird workarounds? Input assumptions? Threading constraints? Comment them!

• Provide Examples — One input/output example beats paragraphs of abstract description.

• Keep Them Updated — Change code, update comments. Make it part of code review.

• Write During Development — Don't leave for later. Write when context is fresh.

• Use Standard Formats — JSDoc, Javadoc, Python docstrings—use your language's conventions.

The Bottom Line

After 15 years and two philosophical earthquakes:

Clean Code is right: Write expressive code with clear names and good structure.

Philosophy of Software Design is also right: Comments capture essential information code alone cannot express.

In the AI era: Comments aren't just for humans. They're context for AI assistants. No excuse for skipping them.

The best code isn't comment-free. The best code uses comments wisely—where they add value, explain context, and make code dramatically easier to understand.

Robert Martin and John Ousterhout aren't enemies. They're two perspectives on the same problem.

Write clean code. Use good names. Keep functions small. And write clear, valuable comments that explain what the code cannot.

Your future self—and your AI coding assistant—will thank you.

What's your take? Have you evolved your philosophy over the years?

📚 Further Reading

Clean Code by Robert C. Martin
A Philosophy of Software Design by John Ousterhout
"Code is read more than written" - The 10:1 ratio
GitHub Copilot Documentation - How AI uses comments
Stack Overflow's Comment Guide