You Learn a Codebase by Changing It | Jake WorthHow do I “get up to speed” in a new codebase? Changing it.<br>After trying almost every alternative— reading code, docs, tickets, metrics—<br>I’ve found nothing that teaches a system faster than shipping a small change.<br>Note: I wrote something similar to this a few years ago, which you can read<br>here: Stop Studying, Start Building. That advice was for people<br>learning to code; this is for starting on a new project, which is something<br>you’ll do again and again a programmer. It’s worth trying to do well.<br>Reading the Code#<br>The first thing I’ve tried is reading the code.<br>It sounds great: cracking the code open like a book. “Chapter one,<br>__mocks__…”<br>Or even starting at a logical entry point like index.ts and following a<br>meandering path through the code.<br>I’ve found this approach to be inefficient. In a new project, it can be<br>challenging to know what code is important. Try as you might, you’ll end up in a<br>few strange, dusty corners.<br>Reading the Docs#<br>Another thing I’ve tried is reading the project docs: READMEs, generated API<br>docs, static HTML docs, and knowledge repositories.<br>If you have them— which is not a given— they’ll cover a fraction of what the<br>application does. They can’t convey the full operational reality of the project.<br>Linus Torvalds once said: “Talk is cheap. Show me the code.” To put it another<br>way, the code doesn’t lie, and being in the code is going to be more<br>authoritative than reading docs.<br>Static Analysis#<br>Here’s a random thing that I’ve tried that’s very me: evaluating the codebase<br>with static analysis tools.<br>Tools like linters, auto-formatters, type-checkers, code quality or test<br>coverage libraries, reading and running tests, or generating visuals like an<br>object-relational diagram.<br>I admire the effort to leverage tooling. But data is not the beating heart of<br>your project. It’s like saying, “It’s a 4/4 song in C major,” when you could hit<br>play on the record.<br>So, how do we do that, you ask? Start making changes.<br>How I Get Up To Speed: Start Making Changes#<br>Here’s my best alternative: pick a small ticket and dive in. In a short time,<br>you’ll learn:<br>How to set up the app<br>Who holds institutional knowledge<br>How tickets are assigned and who “owns” things<br>Team standards for code quality, testing, reviewing, and merging<br>Deployment and verification<br>It’s an organizational speed-run, and that stuff matters. These are not soft<br>skills, they’re hard facts about how your team works.<br>As a bonus, you get to add value to the project immediately. New person is<br>shipping!<br>Start Making Changes#<br>As challenging as it can feel, this is it.<br>Get out there, teaching, asking questions, succeeding, and occasionally failing<br>in public. When you first join a team, nobody expects you to be the expert.<br>That’s the moment to dive in and become a part of the system.
Get new essays in your inbox<br>No spam. Unsubscribe anytime.
Need hands-on help?<br>Hire me ↗