Our codebase is our community

Exploring the broken windows theory

Photo by Mike Erskine on Unsplash

As a project progresses, many of the founding members may have moved on. As time goes by, the team grows, shrinks, new management is brought in. The only thing that remains constant is the code, so it’s natural for new starters to use the codebase to reference what is acceptable.

If you have been working on a project for any real amount of time, you have probably seen a decline in the quality of the code written, multiple patterns to solve the same issue, and a general deviation from the vision the founders of the codebase had once dreamed of.

There can be many reasons for seeing these kinds of things; for me, I attribute quite a bit of it to the Broken windows theory:

The broken windows theory is a criminological theory that states that visible signs of crime, anti-social behaviour, and civil disorder create an urban environment that encourages further crime and disorder, including serious crimes. — wikipedia.

Programmers, what a bunch of criminals and degenerates!

Imagine this, a brand new codebase that everyone is happy working on—the proverbial Green Fields. The team is small, patterns are being established and communicated, pull requests contain useful and meaningful feedback to keep the codebase’s health up.

The best.

Now the product has shipped, and we have delivery pressure to iterate in true agile style. “Just get it doneᵗᵐ” is the word from your Product Owners. There is a defect in production. To “reduce risk”, someone decides to duplicate some code. Maybe they don’t unit test properly, but the PR is approved anyway; after all, it is a defect, and we need to react fast.

This is the first broken window.

Under the broken windows theory, an ordered and clean environment, one that is maintained, sends the signal that the area is monitored and that criminal behaviour 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 behaviour has little risk of detection.

A broken window transmits to criminals (read: engineers) the message that a community (read: codebase) displays a lack of informal social control and is unable or unwilling to defend itself against a criminal invasion.

It’s a bit abstract, but I do like the comparisons drawn. Now, what can we do about it?

Prevention

As always, prevention is better than cure. We need to be vigilant in our feature development (and bug remediation) and be careful not to throw another card on the tech-debt pile. This may take some wrangling with your product owners, but it is well worth the investment.

Pull Requests

Keeping sharp on PRs and code reviews will pay dividends here — this is a two-way street. When creating a PR, make sure you have explained your intentions to make reviewing easier:

How to Make Your Code Reviewer Fall in Love with You

When playing the code reviewer part, it’s important to be empathetic yet honest and thoughtful. Make suggestions and guide instead of blunt this can be improved kind of messages, or worse, just shrug and let the codebase degenerate.

The Boy Scout Rule

If you haven’t at least flicked through Clean Code by Robert C. Martin, I can’t recommend it highly enough. Written over a decade ago, the content rings true regardless of the language you are currently working in. Within the first few pages, he will talk about the Boy Scout Rule.

Leave the campground cleaner than you found it.

The idea is that it’s not enough to write the code well. The code has to be kept clean over time — we must take an active role in keeping our codebase (our environment) healthy. I’m looking at you, Tech Debt.

The cleanup doesn’t have to be something big. Change one variable name for the better, break up one function that’s a little too large, eliminate one small bit of duplication, clean up one composite if statement.

Photo by Gary Chan on Unsplash

Documentation

Good documentation in the form of source controlled markdown documents are way forward here.

A Beginners Guide to writing a Kickass README ✍

Architecture Decision Records (ADRs) are a great way to keep track of any important decisions we have made and make them accessible to anyone working on the project. Often there are reasons for certain decisions, and they should be documented here. For best results, please keep them under source control within the code repo itself.

What’s an Architecture Decision Record?

Wrapping up

Our codebase is our community — individual contributors come and go, but their code lives on long after they are gone.

Keeping a codebase healthy is hard; the longer a project is running, the harder it gets. The Broken Window problem is a snowball, and once it gains momentum, it can be hard to stop.

Invest in the health of your codebase early and often. Future you will appreciate it.


Our codebase is our community was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

Exploring the broken windows theory

Photo by Mike Erskine on Unsplash

As a project progresses, many of the founding members may have moved on. As time goes by, the team grows, shrinks, new management is brought in. The only thing that remains constant is the code, so it’s natural for new starters to use the codebase to reference what is acceptable.

If you have been working on a project for any real amount of time, you have probably seen a decline in the quality of the code written, multiple patterns to solve the same issue, and a general deviation from the vision the founders of the codebase had once dreamed of.

There can be many reasons for seeing these kinds of things; for me, I attribute quite a bit of it to the Broken windows theory:

The broken windows theory is a criminological theory that states that visible signs of crime, anti-social behaviour, and civil disorder create an urban environment that encourages further crime and disorder, including serious crimes. — wikipedia.

Programmers, what a bunch of criminals and degenerates!

Imagine this, a brand new codebase that everyone is happy working on—the proverbial Green Fields. The team is small, patterns are being established and communicated, pull requests contain useful and meaningful feedback to keep the codebase's health up.

The best.

Now the product has shipped, and we have delivery pressure to iterate in true agile style. “Just get it doneᵗᵐ” is the word from your Product Owners. There is a defect in production. To “reduce risk”, someone decides to duplicate some code. Maybe they don’t unit test properly, but the PR is approved anyway; after all, it is a defect, and we need to react fast.

This is the first broken window.

Under the broken windows theory, an ordered and clean environment, one that is maintained, sends the signal that the area is monitored and that criminal behaviour 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 behaviour has little risk of detection.

A broken window transmits to criminals (read: engineers) the message that a community (read: codebase) displays a lack of informal social control and is unable or unwilling to defend itself against a criminal invasion.

It’s a bit abstract, but I do like the comparisons drawn. Now, what can we do about it?

Prevention

As always, prevention is better than cure. We need to be vigilant in our feature development (and bug remediation) and be careful not to throw another card on the tech-debt pile. This may take some wrangling with your product owners, but it is well worth the investment.

Pull Requests

Keeping sharp on PRs and code reviews will pay dividends here — this is a two-way street. When creating a PR, make sure you have explained your intentions to make reviewing easier:

How to Make Your Code Reviewer Fall in Love with You

When playing the code reviewer part, it’s important to be empathetic yet honest and thoughtful. Make suggestions and guide instead of blunt this can be improved kind of messages, or worse, just shrug and let the codebase degenerate.

The Boy Scout Rule

If you haven’t at least flicked through Clean Code by Robert C. Martin, I can’t recommend it highly enough. Written over a decade ago, the content rings true regardless of the language you are currently working in. Within the first few pages, he will talk about the Boy Scout Rule.

Leave the campground cleaner than you found it.

The idea is that it’s not enough to write the code well. The code has to be kept clean over time — we must take an active role in keeping our codebase (our environment) healthy. I’m looking at you, Tech Debt.

The cleanup doesn’t have to be something big. Change one variable name for the better, break up one function that’s a little too large, eliminate one small bit of duplication, clean up one composite if statement.

Photo by Gary Chan on Unsplash

Documentation

Good documentation in the form of source controlled markdown documents are way forward here.

A Beginners Guide to writing a Kickass README ✍

Architecture Decision Records (ADRs) are a great way to keep track of any important decisions we have made and make them accessible to anyone working on the project. Often there are reasons for certain decisions, and they should be documented here. For best results, please keep them under source control within the code repo itself.

What’s an Architecture Decision Record?

Wrapping up

Our codebase is our community — individual contributors come and go, but their code lives on long after they are gone.

Keeping a codebase healthy is hard; the longer a project is running, the harder it gets. The Broken Window problem is a snowball, and once it gains momentum, it can be hard to stop.

Invest in the health of your codebase early and often. Future you will appreciate it.


Our codebase is our community was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.


Print Share Comment Cite Upload Translate
APA
Dean Baker | Sciencx (2024-03-29T10:28:20+00:00) » Our codebase is our community. Retrieved from https://www.scien.cx/2021/04/14/our-codebase-is-our-community/.
MLA
" » Our codebase is our community." Dean Baker | Sciencx - Wednesday April 14, 2021, https://www.scien.cx/2021/04/14/our-codebase-is-our-community/
HARVARD
Dean Baker | Sciencx Wednesday April 14, 2021 » Our codebase is our community., viewed 2024-03-29T10:28:20+00:00,<https://www.scien.cx/2021/04/14/our-codebase-is-our-community/>
VANCOUVER
Dean Baker | Sciencx - » Our codebase is our community. [Internet]. [Accessed 2024-03-29T10:28:20+00:00]. Available from: https://www.scien.cx/2021/04/14/our-codebase-is-our-community/
CHICAGO
" » Our codebase is our community." Dean Baker | Sciencx - Accessed 2024-03-29T10:28:20+00:00. https://www.scien.cx/2021/04/14/our-codebase-is-our-community/
IEEE
" » Our codebase is our community." Dean Baker | Sciencx [Online]. Available: https://www.scien.cx/2021/04/14/our-codebase-is-our-community/. [Accessed: 2024-03-29T10:28:20+00:00]
rf:citation
» Our codebase is our community | Dean Baker | Sciencx | https://www.scien.cx/2021/04/14/our-codebase-is-our-community/ | 2024-03-29T10:28:20+00:00
https://github.com/addpipe/simple-recorderjs-demo