Fellow reader Boonsuen writes in with a great question: How do you make a small change in a large unfamiliar codebase?
what would you do when ur manager ask you to do a "small change" ticket for an existing project that you are new to, and the project is filled with complicated code that is "now bad" due to environment change ~Boonsuen
That's the job! That's what most of us do all day – adding incremental changes to large codebases full of murky swamps and half-forgotten dragons.
Building a new thing from scratch is pretty rare. Being there for the whole lifetime of a product is even more rare. Actually remembering all of it ... impossible.
Just yesterday I sent this meme to my partner joking that I'm both people on the right 😂
Trust the code
You can't remember everything. There's too much. And with other people working on the codebase, it keeps changing anyhow. By the time you're back, it's going to be different than you left it. No point trying to remember.
The code is the source of truth.
What the code says right now is how the software behaves. Not what a design doc says or an architectural diagram or what some senior engineer remembers about how it was originally built and what was the intent. What does the code say right now? That's what matters.
Get comfortable reading the code and following where it leads. Try not to make assumptions. Just read the code.
Find a hook
After you give up your need for control and understanding and learn to just trust the code, the next trick I learned is to find a hook.
This is something I picked up way back in my phpBB modding days. Early 2000's? Back when forums were big and a high school kid like me could have a mod with 10,000+ downloads.
phpBB was a large monolithic mess of PHP. Mods were like plugins that would use a script to modify your installed code with new features.
I had no idea how most of it worked and you'd need a lifetime to read and grok all the code. So here's what I did:
- Find a feature next to what you want to change
- Search for a string, component, anything recognizable
- Follow the code to see how it's implemented
- Make your changes in all the same places
Yes this makes the code worse. Awful separation of concerns, terrible for architectural complexity. But it gets the job done, the ticket closed, and you learn more about the codebase.
Bad code is okay
But I suspect Boonsuen already knows all that. I think secretly they're asking "How do people live like this!? All this code is bad and outdated I can't stand to look at it how can the manager ask me for one small change when the whole thing needs to be thrown out and rewritten from scratch!!??".
The code is bad and that's okay. It works doesn't it? Business processes are running, company's making money, ...
Best you can do is clean up what you can while you're there. Add a comment or small improvement where the code surprised you. Move something to where it's easier to find. Extract a messy blob of code into a function. Wrap a few things that always work together into a module. Move a few files to make a better grouping.
Garden and guide your codebase with love and it will grow into a beautiful garden. But you can't control these things. They have a mind of their own.
Cheers,
~Swizec
Continue reading about Small change in big scary codebase?
Semantically similar articles hand-picked by GPT-4
- Better is good
- What to do when bugs are whack-a-mole
- Are you a boy scout coder?
- You can't stop the business, or why rewrites fail
- Don't neglect your upgrades
Learned something new?
Read more Software Engineering Lessons from Production
I write articles with real insight into the career and skills of a modern software engineer. "Raw and honest from the heart!" as one reader described them. Fueled by lessons learned over 20 years of building production code for side-projects, small businesses, and hyper growth startups. Both successful and not.
Subscribe below 👇
Software Engineering Lessons from Production
Join Swizec's Newsletter and get insightful emails 💌 on mindsets, tactics, and technical skills for your career. Real lessons from building production software. No bullshit.
"Man, love your simple writing! Yours is the only newsletter I open and only blog that I give a fuck to read & scroll till the end. And wow always take away lessons with me. Inspiring! And very relatable. 👌"
Have a burning question that you think I can answer? Hit me up on twitter and I'll do my best.
Who am I and who do I help? I'm Swizec Teller and I turn coders into engineers with "Raw and honest from the heart!" writing. No bullshit. Real insights into the career and skills of a modern software engineer.
Want to become a true senior engineer? Take ownership, have autonomy, and be a force multiplier on your team. The Senior Engineer Mindset ebook can help 👉 swizec.com/senior-mindset. These are the shifts in mindset that unlocked my career.
Curious about Serverless and the modern backend? Check out Serverless Handbook, for frontend engineers 👉 ServerlessHandbook.dev
Want to Stop copy pasting D3 examples and create data visualizations of your own? Learn how to build scalable dataviz React components your whole team can understand with React for Data Visualization
Want to get my best emails on JavaScript, React, Serverless, Fullstack Web, or Indie Hacking? Check out swizec.com/collections
Did someone amazing share this letter with you? Wonderful! You can sign up for my weekly letters for software engineers on their path to greatness, here: swizec.com/blog
Want to brush up on your modern JavaScript syntax? Check out my interactive cheatsheet: es6cheatsheet.com
By the way, just in case no one has told you it yet today: I love and appreciate you for who you are ❤️