Technical Debt

-

 When and How to treat "technical debt"

The term technical debt is the implied future cost of choosing a quick, "good enough" software solution today instead of a more comprehensive, optimal approach. In practice, though, most people view it as cleaning up the code and/or updating to newer/better ways of doing things.

I was recently challenged:

We need to avoid including changes (no matter how small or beneficial) that have nothing to do with the ticket. I understand that this isn't Live code and the containerized version is still a work in progress, but it will make things more difficult for tracking purposes later on. Those changes should be tracked in separate tickets and PRs.

I beg to differ. If you only address technical debt, be it a spelling mistake, formatting, or just better error handling, if you put the requirement that every change needs to be documented and accounted for by some sort of issue tracking system, the overhead and non-sexiness of cleanup will rarely, if ever, get done.

And Gemini agrees with me:

You have hit on one of the most frustrating, universal truths of software engineering: if technical debt requires a dedicated ticket, a product manager will eventually bury it at the bottom of the backlog to die.

Your experience is totally valid. When debt is formalized into a ticket, it suddenly has to compete with new features that bring immediate revenue. Features almost always win.

The short answer? You should do both, but you need to draw a hard line between "Micro-Debt" and "Macro-Debt."

Here is how to strike the right balance so things actually get fixed without you getting bogged down in endless paperwork.

1. The Boy Scout Rule: Handle "Micro-Debt" In-Stride

If you are already working in a file and notice messy formatting, confusing variable names, lack of test coverage, or minor code duplication, fix it right there. Do not create a ticket.

Think of tech debt like dishes in a kitchen. You don't file a ticket to wipe down the counter after making a sandwich; you just do it as part of the process.

  • The 20% Rule: A good rule of thumb is that up to 20% of your time on a feature ticket can be implicitly spent on cleaning up the immediate area you are touching.

  • How to frame it: If anyone asks, this isn't "extra work." This is the cost of implementing the feature correctly and safely. You are keeping the codebase maintainable.

Crucial Rule: The clean-up must match the scope of your ticket. If you are fixing a bug in user_profile.py, don't rewrite the entire authentication module in the same pull request. That leads to scope creep and risky code reviews.

2. When to Actually Fill Out the "Paperwork" (Macro-Debt)

You cannot—and should not—sneak massive architectural changes into a minor feature ticket. If the refactor requires rewriting an entire database schema, switching a major library, or will take more than a few hours, it needs a ticket.

If you try to slide massive changes under the radar, your pull requests will become unreviewable, deployments will get risky, and you will frustrate your team.

3. How to Make Sure Tech Debt Tickets Actually Get Done

If you do have to create a ticket for Macro-Debt, here is how to prevent it from dying in the backlog graveyard:

  • Tie it to Pain, Not Aesthetics: Don't write a ticket that says "Clean up old API code because it's messy." PMs will ignore it. Write: "Refactor old API code to reduce page load time by 400ms and stop flaky CI test failures." Translate the debt into business pain (speed, stability, developer velocity).

  • Advocate for a "Tax" System: Work with your team to establish a dedicated capacity rule. For example: "80% of our sprint goes to features, 20% goes to technical debt and maintenance." This keeps the pipeline moving without needing to beg for permission every single sprint.

  • Group it into a "Fix-it" Day: If tickets are piling up, lobby for a quarterly "Quality Sprint" or a monthly "Fix-It Friday" where the team tackles nothing but the top-voted debt tickets.

The Bottom Line

Leave the campground cleaner than you found it for the daily stuff. For the massive, structural changes, write the ticket—but learn to pitch it as a performance and stability upgrade, not just a cleanup.

Comments

Post a Comment

Popular posts from this blog

Wolters Kluwer

-
  Wolters Kluwer So, I’ve started at Wolters Kluwer—weird name, I know. I was brought on as a Perl dev (backend, build/release, Linux admin), but suddenly I’m being tossed into the deep end of a super complex frontend. The real kicker? Everyone assumes I’m already a pro at this stuff. I never claimed to be, but the pressure is definitely on. Here’s the "short" list of things they expect me to just know , even though I’ve barely touched most of them: The Frontend Maze: JavaScript, jQuery, Ajax, SPAs, route handlers, and event listeners. The "Ovid" Ecosystem: It’s a massive app with a million ways to do the same thing. If you don't know the exact "UI path flow," you’re just chasing ghosts. The Tooling: Black Duck, Google Analytics, Open Telemetry, and Jenkins pipelines. The Meta Stuff: JIRA's crazy process flows (there are like 20 "similar" dropdown options for one task), Redis, and deep HTML/template structures that go way beyond basic...
Read more

Contingent worker - Code Games

-
A little chat with Gemini about Contingent workers and code games What is a "contingent worker'? A contingent worker is an individual who is hired by an organization on a non-permanent, as-needed basis. Unlike traditional employees, they do not have an implicit or explicit contract for long-term employment. Instead, their relationship with the company is "contingent" upon a specific project, a set period of time, or a particular business need. The term serves as an umbrella for several different types of work arrangements: Independent Contractors / Freelancers: Self-employed individuals who provide specialized services. They typically manage their own taxes and equipment. Consultants: Experts hired to provide professional advice or technical skills for specific organizational challenges. Temporary Agency Workers: Individuals employed by a staffing agency but "loaned" out to a client company for short-term assignments. Gig Workers: People who use digita...
Read more

The 5 AM Contract

-
Image
When "East Coast Time" Becomes "Anytime" When I signed onto this contract, I agreed to align with East Coast hours. In the world of standard business, that’s a clear 9-to-5 frame—or for me on the West Coast, a manageable 6 AM to 2 PM. It’s an early start, but it’s a fair trade for synchronization. Lately, however, those boundaries have begun to dissolve into a 24/7 "always-on" expectation that is as exhausting as it is unproductive. It started with "Code Games" initiatives creeping into my personal life—specifically, receiving texts on a Sunday morning to spend time looking into upcoming events.  Then came the after-hours messages once my 2 PM PDT cutoff had passed.  Now, the line has moved again: meetings are being scheduled for 5 AM. There is a massive difference between starting early to support a team and being expected to sacrifice sleep and weekends for non-urgent tasks. When we shift the "standard" day earlier and earlier, or rea...
Read more