Gemma Lara Savill
Working with a big codebase. The broken window theory.
By Gemma Lara Savill
Published at October 14, 2023
You have a big team that has produced a big codebase. Developers come and go. Time goes by and this starts to remind you of the Broken Window Theory.
What is the Broken Window Theory?
Social scientists James Wilson and George Kelling first introduced the broken windows theory in an article titled "Broken Windows", in March 1982.
Under the broken window's theory, an ordered and clean environment, one that is maintained, sends the signal that the area is monitored and that criminal behavior is not tolerated. Conversely, a disordered environment, one that is not maintained (broken windows, graffiti, excessive litter), sends the signal that the area is not monitored and that criminal behavior has little risk of detection.
The theory assumes that the landscape "communicates" to people.
My software version of this theory.
Imagine that you meet your new project: a big codebase full of lines and lines of code. The "landscape" will soon speak to you.
If you find yourself before a picture of "broken windows", some code "graffiti" and even small patches of "litter", the best thing you can do is start repairing windows and clearing up.
Even better, lead by example and start working to get the whole neighborhood (your team) involved.
Where do I start?
- Reading. Read a lot of code. All you can. Try and figure it out. When you fully understand what a function, class or module does, if it is not apparently clear for others, document it. This will help other team members spend less effort when they come across this block of code for the first time.
-
Investigate and document. You can document via well-placed code comments. Focus on the why and not the how.
Write "how to" guides in a common place (not in the code, a wiki somewhere), so that your team can easily find answers and contribute. - Testing is another good source of documentation. When tests are well written you can quickly catch on to what that part of the code is written for. What this code should do and what it should not. Good tests can alert you of possible edge cases. And if, when you break your first window in this new place, you will be the first one to know.
Good, careful testing is also a strong signal that this team cares. If we break a window or leave an empty cup of coffee on a shelf somewhere, we want to be warned, find out fast to make it right.
Small refactors
Make the code more readable. Even better, make it scannable. It should allow you to scroll lightly through the code and still make sense of what is going on, in a big picture sense.
You don't want to mentally go into, and process, a lot of conditional statements to understand what a piece of code does. Break it down. Refactor parts of the code into smaller functions.
This will pay off if you need to make a larger refactor down the line. Drop in some tests, and you are halfway to making that big architecture change you might have in mind, a faster and safer journey.
Robert C. Martin famously said "Functions should do one thing. They should do it well. They should do it only." Clean Code.
Remember that we are on a quest to fix all the broken windows, but we also need to keep the coding landscape in top shape. Don't enforce rules, like mandatory test coverage percentages, but create team agreements.
Start small, like a common linter to reduce noise of moved margins in pull requests. You can move on to promoting common naming conventions within your team. Just having an open discussion about it will make the point that it matters, and we care.
Streamline dependencies, like mocking or assertion libraries. It is easy to suddenly end up with two similar libraries. Keep it tidy and this will also help reduce build times.
There is no better onboarding to a new project than a clean and maintained codebase.
This signals a caring environment of developers, united on the quest of making the codebase a better place.
So remember, don't let broken windows populate, fix them, and keep them new and pretty.
You will soon be in a better place. A happy place.
Sources:
- Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin
