The Developer's Guide to Technical Debt

Yes, but do it constructively. When you spot something that looks like debt, ask questions rather than making accusations. "I noticed this pattern - is there a reason it's done this way?" works far better than "This code is terrible." Keep a running list of things that confuse you or slow you down. That list is valuable data your team needs, and fresh eyes catch things veterans have stopped seeing. If your team has a debt backlog, add items there. If they do not, that is itself a conversation worth starting.

Start with tests. If the code you want to refactor does not have tests, write characterization tests first - tests that document what the code actually does right now, not what it should do. Then refactor in small steps, running tests after each change. Never mix refactoring with feature work in the same commit. Use feature flags if the refactoring is large enough that it cannot be completed in a single day. The key principle: make the change easy, then make the easy change. See our techniques guide for specific refactoring patterns.

Apply the boy scout rule: leave code a little better than you found it. When you touch a file for a feature, clean up one thing while you are there - rename a confusing variable, extract a method, add a missing test. These micro-improvements add up fast and do not require separate tickets or permission. Also, start tracking the time you lose to debt - "I spent 3 hours working around the payment module's limitations" is concrete data your lead needs. When you can show that debt is already costing time, the "we don't have time" argument flips. See selling to management for how to build that case.

It depends on the scope. Small, localized improvements - renaming, extracting methods, adding types - absolutely do it in the same PR. For larger structural changes, create a separate ticket and PR. Mixing big refactors with feature work makes code review harder, makes rollbacks riskier, and muddies the commit history. A good rule of thumb: if the refactoring touches files your feature does not need, it belongs in its own PR. If it only touches files you are already changing, include it but keep the refactoring in separate commits.

Stop talking about code quality and start talking about delivery speed. Track concrete metrics: how long features take in debt-heavy areas vs clean areas, how many bugs originate from known debt, how much time is spent on workarounds. Present a specific proposal - not "we need to fix everything" but "if we spend 2 sprints on the payment module, feature delivery in that area will go from 3 weeks to 1 week." Make it about outcomes, not aesthetics. Our measuring guide and selling to management page have frameworks for this.

Tech debt is a deliberate or inadvertent trade-off where you accept a suboptimal solution now, knowing it will cost more to change later. Bad code is just bad code - no trade-off was made, no value was gained. The distinction matters because tech debt implies a rational decision (ship now, fix later) while bad code implies a skill or process gap. In practice, both slow you down, but the fix is different: debt needs prioritization and scheduling, while bad code needs better reviews, mentoring, and standards. The original debt metaphor from Ward Cunningham was specifically about shipping a first version to learn from users - not about writing sloppy code. See what is tech debt for the full breakdown.