How can devs prevent technical debt from accruing?


- Follow the codebase’s standards

- Write tests

- Encourage a code review culture

- Have happy developers

- Make documentation easy to find

- Use a project management system

- Write high quality code 

Developers spend 1/3 of their time on technical debt. Maintaining legacy systems is what devs claim to hinder their productivity the most. It also hurts the team's morale. 

How can dev teams prevent technical debt from accruing?

Follow the codebase’s standards

Teams have a series of rules that they have agreed upon. These are some commonly found items across different teams:

-Linting: ESLint, SonarLint, etc. There are a lot of linting tools out there that are useful for software engineering teams to follow a syntactic standard that favors the code’s readability in a certain way. Simply agree on one, and be sure to always commit and push following those linting standards. Even better, automate it on every commit and push.

-Naming: Codebases have naming conventions for modules, files, functions and variables. When everyone on the team adheres to such standards, finding code becomes way easier. It becomes natural to navigate between files and modules. You can read the name of a function or a variable and immediately understand what it does. 

Write tests

This practice is standard to guard developers against a future liability, yet it's not so common in early-stage projects. The earlier you think about it, the less debt will be accrued later on.

It’s totally fine (even encouraged) for early stage startups to not write tests. What gets them to an initial level of success is not code scalability, but speed of iteration. At some point this needs to change, and knowing when to have such tradeoffs is both art and science. 

Regardless, when that tradeoff happens, write tests. The earlier you are the more contrarian it will be. The later you are, the more orthodox it will be. Know when to do the switch. Trust your gut feeling on this one. 

Refactor if needed

Along those lines, understand that deadlines are arbitrary (unless there is a cash constraint) and refactor code if needed. 

This is important for preventing technical debt because it makes the  code more readable, debuggable, and maintainable. 

Books about code refactoring guidelines have been written. Generally speaking: Make functions as short as possible, don’t return a calculation that mixes high-level with low-level abstractions, avoid duplicate code, if statements should be at the top of a function, and avoid code that produces side-effects. 

Encourage a code review culture

Devs will have to give a quality check to each other's code in order for it to be merged to the dev and/or the main branch. It will also help your team osmote technical knowledge.

A high-quality code review process involves making everyone do pull request reviews (including junior folks), checking for code readability, making sure that the pull request creates passive documentation, testing performance, checking for potential security risks, and checking for testability. 

Have happy developers

Developers don't necessarily want a ping pong table, free beer, and a PlayStation to be happy. 

They want autonomy in their work. This means allowing them to work from wherever they want, and hopefully whenever they want. It also means not micro-managing them.

If they are happy, they will take more ownership of their codebase. They will go a step further and prevent technical debt. 

Make documentation easy to find

Whether it's code comments, a README/wiki, or passive documentation across ticketing, git, and messaging systems (hopefully a mixture of all); make it easy for your developers to find the most relevant pieces of documentation for a given file.

We’re obviously biased here, but you can use our VS Code extension to do so. 

Technical debt accrues when people write bad code. People write bad code when they don’t have enough context about the codebase to write high-quality code. 

This is the reason why we built watermelon. Because we suffer from this as software developers. 

We are your code context toolbox. We help you get the most relevant pieces of technical information for a given block or file of code, saving you hours of searching through the company’s code documentation. 

You can find us on the VS Code marketplace

Write documentation at each commit

As Rémy suggests, it’s important to write documentation at each commit with a given standard

This is very hard to implement because it’s not something that developers have as a habit, but in the end it’s worth it. Good documentation helps developers:

  • Understand what code does
  • It will help justify code that looks like crap, but had to be that way because there were not too many options
  • Writing documentation as you write code helps you as a developer be aware of bugs that you might’ve had forgot

Use a project management system

We are software developers and I know what you’re thinking right now (depending on the ticketing system your company uses) because I used to feel the same way: “Ticketing systems suck”. However, they are very important. 

First, this allows the dev team to have synergy. To have better cross-functional collaboration. Without a ticketing system, teams would work sub-optimally. People would work on the same task when they shouldn’t, because they could’ve divided and conquered. Doing

It also helps pay technical debt faster. If there's an issue identified, it should reach the developers right away.

Maybe the UI of these systems isn’t the best, we agree. We recommend using a tool like Halp if you prefer Slack’s UI

Write high quality code 

Scaffold the project correctly. Don't repeat yourself. Have descriptive variable and function names. Anticipate yourself for what's gonna fail.

Is your code extensible, and easy to edit for non-authors? Is it well tested against edge-cases? 


It’s very important to anticipate technical debt at your company. It isn’t 100% inevitable, but you can prevent a considerable amount of it by following this guide we have written for you. 

Follow the codebase’s standards, write tests, refactor if needed, encourage a code review culture, have happy developers, make documentation easy to find, write documentation at each commit, use a project management system, and write high quality code. 

Happy coding :)