Imagine a situation where you know exactly what you’re looking for, the specific function, the precise line of code, even the exact token causing the issue. And yet, you can’t find it. You’re scrolling endlessly, bouncing between files, and questioning whether what you’re searching for even exists. If this sounds familiar, you’re not alone.
In this article, we will explore what to do when a codebase becomes large and is composed of multiple pieces. Just moving around can be hard, time-consuming, and error-prone. We will also discuss ways to mitigate some of these headaches, leading to faster deployments and cleaner development cycles.
Understanding Your Codebase
As services and products grow, complexity in the codebase is inevitable. However, if that complexity is not managed, it becomes chaos. The ability to read code goes beyond understanding the few lines you can see on screen.
Consistency is one of the most powerful tools for taming the chaos of an ever-growing codebase. It makes actions repeatable and explainable.
A good start for making things consistent is to align your codebase with the design architecture of your application or service. If your code is well-organized, and your files, folders and repositories make sense from an architecture perspective, navigating becomes a process of following threads, not mindless clicking.
Navigating the Codebase
We all know that one person who uses Vim, thirty keystrokes and one second later, they’re exactly where they need to be. This efficiency comes from good, predictable design patterns. When both your code and folder structure follow a logical pattern, navigation becomes a matter of jumping directly to what you need, rather than pulling at loose threads until you stumble across it. If you can only find things by searching for them, your environment isn’t organized.
The key question to ask is: “If someone new to the codebase were given an explanation of the layout, could they reasonably guess where something might be?”
Organization isn’t just about the code itself or repository structure, it extends to folder and file names as well. Using a linter and making smaller and more modular blocks are your first defense in keeping the environment easy to navigate. They provide the ability to skim through all the text on your screen and not have to read each line while navigating through it.
When everything is readable and well-structured, comments should be reserved for explaining why something is done, not what it does. If you find yourself writing comments to explain what a function does, it’s a sign that your naming and structure might need improvement.
Leveraging Naming Conventions & Readability
Naming conventions matter, it’s a conversation that every engineer has had at some point. Rather than advocating for a specific convention, the key takeaway is that consistency and readability are of the utmost importance. One of the greatest strengths of PowerShell, for instance, is its consistent verb-noun naming pattern, which makes it instantly clear the action a command is taking. Names should always be verbose enough to explain what they contain or do.
Using Automated Tools for Faster Troubleshooting
Understanding your tools and knowing how to use them effectively can save significant time during troubleshooting. One of the most underrated features of many Integrated Development Environments is its colour scheme and syntax highlighting. These features enhance readability when scrolling, and help differentiate objects within functions. My personal favorite is Catppuccin.
Learning a new tool can save hours, however the cost of that learning is time, and it will always be upfront. For example, learning how to use VS Code, both the panels, json configuration, and its plugin system can help to integrate with third party services like AWS SAM, allowing you to deploy without the console.
Don’t hold yourself back, experiment with tooling. VS Code, and other IDEs, usually have a large range of plugins to help in development, from correcting spelling errors to the ability to integrate into your command line and help debug.
Letting team members use the tools they’re comfortable with is fine, but the key is ensuring that the output adheres to a standard, not the tool itself.
Building a Culture of Maintainability
As the codebase grows and team members come and go, maintaining organization becomes increasingly important. While it doesn’t take much time to uphold standards, it’s easy to take shortcuts.
Remember: a five-minute shortcut now could cost another team member 20 minutes of head-scratching later. Fostering a culture where code is not only functional but also properly structured helps improve team cohesion. This can be done in a few simple steps: documenting decisions and PR reviews as a team can really help in understanding and getting to know the codebase, even if you are not directly working with it.
Saving time for small incremental refactors helps keep everything suggested in the article on track, and avoids losing time to bigger changes.
Conclusion
Setting clear standards, more importantly, documenting them, is extra effort at the start. It’s a front-loaded task, but even 30 minutes of documentation and a few basic guidelines for new team members can save hours of lost time searching through a complex environment or tracking changes across multiple repositories.
As always, the best time to start organizing your workspace was when you first wrote it. The second best time is now. The sooner you start, the sooner the chaos is tamed.
We offer hands-on AWS training as part of our SaaS Growth subscription, to help your team make the best use of the AWS cloud. Book a free chat to find out more.
For some topics, you can also get the same training just on the topic you need - see our Terraform training and Kubernetes training pages.
This blog is written exclusively by The Scale Factory team. We do not accept external contributions.
