The Junior Developer's Guide to Tech Debt
You don't need 10 years of experience to make a difference. Here's how to recognize tech debt, avoid creating more, and have productive conversations about quality.
What You're Walking Into
Every codebase you will ever work on has technical debt. Every single one. The codebase at your first job, the side project your team lead built on a weekend, the enterprise system that has been running for 15 years -- they all carry decisions that made sense once but cost time and effort now.
This is not anyone's fault. Tech debt accumulates naturally as requirements change, teams grow, deadlines hit, and technology evolves. The developers who came before you were not careless -- they were making the best decisions they could with the information and constraints they had.
Here is the good news: as a junior developer, you bring something incredibly valuable to the table. You see things that experienced developers have stopped noticing. Confusing naming? You will spot it because you are learning the codebase for the first time. Missing documentation? You will feel that pain immediately. Overly complicated setup? You just went through it.
Your Fresh Eyes Are Genuinely Valuable
Your "fresh eyes" perspective is genuinely valuable. If something confuses you, it probably confuses others too. That confusion IS tech debt. It slows down onboarding, increases the chance of mistakes, and makes the codebase harder to maintain. When you struggle to understand something, you are identifying a real problem -- not exposing your inexperience.
Recognizing Tech Debt
You do not need a special tool to spot tech debt. These eight signs show up in nearly every codebase, and you will probably recognize several from your own experience.
Code That Scares You to Touch
If you open a file and immediately feel anxious about making changes, that is a signal. Code should not inspire fear. When developers avoid touching something because they are afraid of breaking it, bugs accumulate and features take longer to ship.
"Don't Change That, It Might Break Everything"
When a teammate warns you away from a section of code with no further explanation, that is tech debt talking. Well-designed systems can be modified safely. If a change in one place can break something unexpected somewhere else, the system has hidden coupling that needs to be addressed.
Copy-Paste Code in 3+ Places
When the same logic appears in three or more places, fixing a bug means finding and updating every copy. Miss one and you have an inconsistency. Duplicated code is one of the most common forms of tech debt and one of the easiest to fix once you spot it.
Tests That Nobody Trusts
Flaky tests that pass sometimes and fail others, or test suites so outdated that everyone ignores their results. When the team says "oh, that test always fails, just ignore it," the test suite has lost its purpose. Tests that cannot be trusted are worse than no tests -- they create false confidence.
Documentation That Says "TODO"
README files with placeholder text, API docs that describe an older version, or inline comments that say "TODO: explain this later." Documentation debt is invisible until someone new joins the team and spends three days figuring out what should have taken thirty minutes to read.
Setup That Takes More Than a Day
If getting a new developer's environment running takes more than a day, that is a clear sign of accumulated process debt. Every hour a new team member spends fighting environment setup is an hour they are not productive. Multiply that by every new hire, every laptop replacement, and every CI/CD rebuild.
Workarounds With No Explanation
Code that does something strange with no comment explaining why. A mysterious sleep(500) before an API call. A function that converts data to a string and back to an object for no apparent reason. These workarounds probably fixed a real bug once, but without context they become landmines for future developers.
"We'll Fix It Later" (But Later Never Comes)
The most honest sign of tech debt is the verbal acknowledgment that it exists combined with zero plan to address it. "We'll fix it later" is how tech debt grows from a minor annoyance into a major blocker. If there is no ticket, no timeline, and no owner, later is never.
How NOT to Create More Debt
The best way to fight tech debt is to stop producing it. These six habits will not slow you down -- they will actually make you a better developer faster.
Write Tests for Code You Write
Not just the happy path. Test what happens when inputs are empty, null, or unexpected. Test the error cases. If you only test the scenario where everything goes right, you are leaving the most important paths uncovered.
Start here: For every function you write, add at least one test for the expected case and one test for an error case.
Ask "Why" Before Copy-Pasting
When you find a pattern in the codebase and copy it for your new feature, pause and ask: is this pattern the right way to do it, or is it just the way it was done last time? Copying a bad pattern spreads tech debt to new places.
Start here: Before copying code, ask a teammate: "Is this the current recommended pattern, or is there a better way now?"
Use Descriptive Names
Future you is a stranger. Six months from now, you will not remember what d, temp, or data2 meant. Name variables, functions, and files so that someone reading them for the first time can understand what they do.
Start here: If a variable name needs a comment to explain it, the name is not descriptive enough.
Don't Suppress Linter Warnings
It is tempting to add a // eslint-disable comment when a linter flags your code. But linter rules exist for a reason. Before suppressing a warning, understand what it is trying to protect you from. If you truly need to suppress it, add a comment explaining why.
Start here: When a linter flags something, Google the rule name before disabling it. You will learn something every time.
Document Your Decisions
Even small ones. When you choose approach A over approach B, write a quick comment or note explaining why. "Used polling instead of websockets because the server does not support WS yet" saves the next developer from re-investigating the same decision.
Start here: Add a one-line comment whenever you make a non-obvious choice. Explain the "why," not the "what."
Ask for Code Review
Even when it is optional. Code review catches mistakes, spreads knowledge across the team, and teaches you patterns you did not know existed. The feedback you get from reviews will accelerate your growth faster than anything else. Do not treat it as a gatekeeping exercise -- treat it as free mentorship.
Start here: Request a review on every PR, even small ones. Ask specific questions: "Is this the right pattern for error handling here?"
Having the Conversation
Bringing up tech debt as a junior developer can feel intimidating. The key is framing. You are not criticizing anyone's work -- you are helping the team move faster. Here is how to get the tone right.
"I noticed this pattern repeats in three files. Is there a reason for it, or should I create a ticket to consolidate it?"
"Who wrote this terrible code?"
"This module took me 3 hours to understand. Could we add some documentation so the next person ramps up faster?"
"This codebase is a mess."
Frame Issues as Future Risk, Not Past Blame
The most effective way to discuss tech debt is to focus on what it costs going forward, not who caused it in the past. Nobody wants to hear that their code is bad. Everyone wants to hear how the team can ship faster and more reliably.
Instead of "this is wrong," try "if we keep this pattern, here is what it will cost us in the next quarter." Numbers, timelines, and specific risks are persuasive. Vague complaints about code quality are not.
The Boy Scout Rule
"Leave the code a little better than you found it."
You do not need permission to make small improvements. Every time you touch a file, look for one small thing you can improve while you are there. These tiny changes compound over time into a significantly better codebase -- without requiring a special "tech debt sprint" or management approval.
Rename a Confusing Variable
Change d to deliveryDate. Change tmp to unsavedChanges. Small renames make a big difference in readability.
Add a Comment Explaining Non-Obvious Logic
If you spent time figuring out why code does something unexpected, leave a comment so the next developer does not have to repeat your investigation.
Delete Dead Code You Confirmed Is Unused
Commented-out blocks, unused functions, unreachable conditions. Verify they are truly dead, then remove them. Less code means less confusion and less maintenance.
Add a Missing Test
If you are modifying code that has no tests, add a test for the behavior you are relying on. Even a single test for the critical path is better than none.
Update Outdated Documentation
If you notice a README step that no longer works, or an API doc that describes old behavior, fix it right then. Stale docs are worse than no docs because they actively mislead.
When to Escalate
Not all tech debt is created equal. Some issues you can fix yourself, others need team discussion, and a few need immediate attention. Here is how to decide.
Security Vulnerability
Tell Your Lead NOWExposed credentials, SQL injection, unvalidated user input going to a database, unencrypted sensitive data. Do not wait for standup. Do not open a ticket first. Walk over (or message) your team lead immediately. Security issues can cause real harm to real people.
Blocks Your Work
Discuss in StandupIf tech debt is actively preventing you from completing your assigned work, bring it up in your daily standup or team sync. Explain what you are trying to do, what is blocking you, and how long the workaround takes. Let the team decide whether to address it now or find a different path.
Risky But Not Blocking
Create a Ticket With NotesYou found something that could cause problems down the road but is not blocking you right now. Create a ticket with details: what you found, where it is, what the risk is, and any ideas you have for fixing it. Include specific file paths and line numbers. A well-documented ticket is infinitely more useful than a vague complaint.
Minor Annoyance
Fix It (Boy Scout Rule)A confusing variable name, a missing comment, an outdated import. These are small enough to fix while you are already in the file. Do not create a ticket for a two-minute fix -- just include it in your current PR with a brief note in the commit message or PR description explaining the cleanup.
Frequently Asked Questions
Yes, but with respect and context. Start by understanding why it was written that way -- there may be a reason you do not see yet. If you still think it should change, propose the refactor in a code review or ticket rather than just changing it silently. Frame it as an improvement, not a correction. Senior developers generally appreciate juniors who think critically about code quality, as long as the approach is collaborative rather than combative.
Lead by example in your own code. Write clean code, add tests, document your decisions, and make small improvements when you can. Over time, teammates notice when your code is easier to review and your features have fewer bugs. You cannot force a culture change, but you can demonstrate the benefits. If the environment is truly hostile to quality, that is also useful information about whether this is the right team for your growth.
Read other people's code regularly, not just your own. Review PRs even when you are not assigned. Read open-source projects to see how experienced developers structure code. Keep a personal list of patterns that confused you and look for them in other codebases. The more code you read, the faster you develop an instinct for what "feels off." Also, study the common types of tech debt -- code debt, architecture debt, test debt, documentation debt -- so you have a vocabulary for what you are seeing.
Absolutely. Asking "why" is one of the most valuable things a junior developer can do. Sometimes the answer reveals important context you need. Other times, the answer is "no good reason" -- and that question just identified tech debt. Phrase your questions with curiosity rather than judgment: "I noticed we do X here. Can you help me understand the reasoning?" works better than "Why is this done wrong?" Good teams encourage questions because they surface assumptions that everyone else has stopped examining.
You will. Every developer does, at every level of experience. The important thing is what happens next. If you realize you shipped something that could be better, file a follow-up ticket, mention it in your next retrospective, or fix it in your next PR to that area. Tech debt is not a moral failing -- it is a natural byproduct of building software under real-world constraints. The goal is not zero debt. The goal is awareness and steady improvement.
As a junior developer, most of your time should go toward features and learning. But you can address tech debt without dedicating separate time to it. Use the Boy Scout Rule to make small improvements as part of your regular work. If you spend an extra 10 to 15 minutes per PR cleaning up what you touch, that adds up to meaningful improvement over weeks and months. For larger debt items, create tickets and let the team prioritize them alongside features. Most healthy teams aim for 15 to 20 percent of capacity on maintenance and debt reduction.
Keep Growing Your Skills
Ready to level up? Explore our guides for experienced developers and practical habits you can start using today.