Many software teams eventually find themselves owning code that they didn’t write. Maybe the charter of the team changed during a reorg. Maybe there was an influx of new engineers. Maybe there was an acquisition. Whatever the case, if a team has never seen a codebase, it will be hard for them to even maintain it, let alone improve or extend it. How do you ramp up a whole team quickly?
Late last year, my team took over Watershed’s financial value mapping system, a codebase of about 16,000 lines that associates emissions factors to each of an organization’s financial accounts. It’s a critical step in the measurement process for most of our customers, as it allows us to estimate Scope 3 emissions from an organization’s expense data. Given that, it was crucial for us to get up to speed, and fast! To do that, we came up with an approach we call an ATTACK. Read on to learn:
- What in the world ATTACK stands for
- how our ATTACK went, and
- how other engineering teams can use an ATTACK to get up-to-speed on a new codebase
Adding Tests To Augment Code Knowledge
ATTACK stands for Adding Tests To Augment Code Knowledge. As contrived as the acronym may be, the idea is simple: by adding tests to an unfamiliar codebase, a team can quickly build code-level familiarity. The approach is widely applicable — it doesn’t matter how junior or senior the engineers are, nor what language the project is written in. And though there’s no shortage of strategies for getting familiar with a new codebase, an ATTACK has two nice benefits:
- Shipping code immediately: there’s no better way to learn a codebase than to try and change it. But change is risky! Tests are a safe way to get familiar with the SDLC of a new area.
- Illuminating documentation: any documentation that the codebase comes with will prove valuable. But reading documentation can be tedious if an engineer has no practical experience for it to “attach” to. Writing tests provides a stronger context for the crucial information within documentation.
Implementation
Before embarking on our ATTACK, we agreed on the following three goals:
- Become more familiar with surface area: The main thing we wanted was for everyone on the team to feel comfortable working with and talking about the financial value mapping codebase.
- Practice writing new kinds of tests: We thought this was a perfect opportunity for engineers to write tests they hadn’t before, such as React component tests or Temporal workflow tests.
- Increase test coverage and documentation: Though the existing code already had many tests, we identified some places that could use more.
We knew preparation would be very important for the success of the ATTACK. One member of the team took some time to get familiar with the codebase by reading documentation, playing with the product, and talking to members of the previous owners as necessary. Then, they came up with a list of the important units — like classes, workflows, and functions — and highlighted the ones most in need of testing (detailed, file-level coverage metrics are best, but even a simple count of tests would be a good start).
Once we had this preliminary idea, we ran our ATTACK like a hackathon. To start, that same member of the team gave a quick introduction on the code and areas for improvement, and everyone picked an area to focus on. Then we took two full days to do nothing but add tests. Finally, we each took turns sharing what we’d done and what we’d learned.
And the results? More than a dozen new tests, as well as a handful of code cleanups and refactors. We also added end-to-end tests, which financial value mappings didn’t have before, and gained valuable experience with Playwright as a result. And most importantly, we built confidence as new owners of the code! The value of that became evident as we took on the day-to-day maintenance of the product as a team.
Tips and tricks for a successful ATTACK
For any team looking to implement their own ATTACK, here are a few pointers:
- As much as possible, make sure tests are easy to add — you want your team reading code, not wrestling with test infrastructure. We also had some outstanding internal testing guides to lean on.
- It’s useful to make a “code tour” — a document containing links to the important units in the codebase. This will help the team get oriented with the unfamiliar code during the ATTACK, but will also prove useful afterwards. A glossary of common terms will also prove useful.
- Two days of testing felt right for us, but whatever you decide for your ATTACK, make sure to protect that time! Also note that for distributed teams, it can be helpful to do the kickoff the day before you begin, so that everyone can hit the ground running the next day (and be less likely to get sidetracked).
- Share learnings at the end. Before we started, we asked the team to come prepared with how many tests they added (or percentage coverage after their tests), as well as some interesting tidbit they learned from the code — could be a bit of surprising logic, a bug, or even a fun code comment.
- And lastly — make it fun! The hackathon-like vibe was a big part of this for us, as well our decision to pair up (and pick silly team names). It’s also a great opportunity to encourage people to work with others that their normal work doesn’t usually bring them in contact with.
