If you are a software engineer, chances are you came across a number of principles which constitute software development best practices. Many of these are known by somewhat cryptic acronyms, such as SOLID, DRY or KISS, and you got to know them either intentionally (you learned by yourself/a more senior colleague taught you) or unintentionally (you got roasted during a job interview). I believe all of aforementioned three are essential and highly encourage you to follow them if you aren’t already — they won’t be the topic of this post, however.
The one I wanted to talk about is a rule that is so simple that in my opinion it often gets omitted as “too obvious to mention”. Heck, it doesn’t even have it’s own Wikipedia page! As you may have already guessed from the title, it’s the Boy Scout rule.
I’m not exactly sure who coined the term within software development context — it may have been Uncle Bob (aka Robert C. Martin), possibly in his excellent book, Clean Code:
Always leave the code you are editing a little better than you found it.
As simple as that. But how should that work in practice? Let me give you some examples:
- you need to add a new method to a class and notice that its existing methods contain duplication, so you extract a private method to remove it,
- a variable you need to use has a poor name that doesn’t convey its intent (you probably had a hard time locating it in the first place), so you rename it to be more meaningful,
- a tool you need to use is missing documentation, so you add one after figuring out how it works,
- a script you need to use is hardcoded to old values which are not accurate anymore, so you update them,
- a function you need to edit is missing unit tests, so you add them to cover both your new and any existing cases as well,
- your IDE highlights some warnings in the code you need to work with, so you fix them (this is ofttimes as easy as pressing Alt + Enter).
Et cetera, et cetera. A bit of cleanup here, a refactor or two there — small improvements that cost little to no time and make work easier for everybody, including future you. The beauty of Boy Scout rule is that when it’s taken to heart and applied by entire team, all the contributed improvements will incrementally stack up and reduce tech debt by a visible margin, all essentially “for free”.
PS: keep in mind that we’re talking about small improvements. Be reasonable and don’t overdo it. I can imagine your daily schedule is already quite packed and delivering quality features on time should always be a priority. Same for your work-life balance — it’s not about being a “hero” who stays in the office until late hours to refactor half of the app!
Don’t let your help get in a way
While Boy Scouting is beneficial, it’s important to be aware that it can sometimes introduce disturbance to actual work — more specifically, the code review process.
The problem arises when an improvement obscures the actual change that you have to make as a part of your task. This usually happens when things get renamed or packages are moved around, as those often lead to dozens of files getting modified. Additionally, a Boy Scouting change can often be completely unrelated to what you actually need to do.
It’s in everyone’s best interest to keep pull requests small and focused on one thing only, as they can then be reviewed quicker and with ease. What can we do then to eat the cake and still have the cake?
From my experience there are a couple of solutions that work. First one is to annotate your pull request with comments to guide reviewers. If the improvement is small, then just highlight it so that the reviewer is not surprised when they find it. If it’s bigger, then you may need to do it the other way around — mention that the pull request includes an improvement and point the reviewer to places that contain the actual feature you were working on.
If all fails, there is nothing wrong with simply creating a separate pull request with your Boy Scouting change. It’s actually the cleanest approach, but it requires a bit of extra work — isn’t putting a little extra effort all that Boy Scouting is about though? :)
Last but not least — remember to praise others for their Boy Scouting. They had their best intentions and made you a favour after all. If a situation arises where such an improvement makes code review difficult for you, thank them first and only then ask to add some guidelines or split the pull request.
Supply instead of demanding
A tricky thing about Boy Scouting is that even though it’s called a “rule”, you can’t really enforce it.
Code review comments such as
This block is duplicated across the class — consider extracting a function to conform to DRY rule.
Adding this functionality here will break the Single Responsibility principle, what do you think about creating a new class instead?
are quite common. But asking somebody to provide ad-hoc changes not related to problem at hand will turn out awkward at best and exclude you from the lunch order thread at worst. This is something a person has to do out of their own good will, so keep it in mind or risk becoming “that” guy.
Instead, be sure to act as an example and spread the word — mention it during a coffee break, send people articles, and, more importantly, praise teammates who take the extra effort.
Go beyond your own code
A couple of times I’ve seen an attitude where people hold on to a division between “us” and “them”. They made a typo in function name. They are using an outdated serialiser library. They forgot to log that particular error case.
It’s usual in multi-team and/or multi-vendor environments, but that’s not a rule. Nevertheless, the story is usually the same. People throw their hands up in the air and blaming begins — “we can’t do our work properly because of them”.
If the matter is more urgent, a bug will be reported and the fix will arrive in some unforeseeable future. If it’s something not too relevant, it will just stay there and keep annoying everyone until someone takes the initiative and fixes the thing. Why not be that person?
Given the project’s environment makes it possible for you to provide a quick fix and submit a pull request for another team, just go for it and do it! I know that what I’m going to say now may sound like some kind of black magic, but doing people favours is how you build good relations and possibly even friendships. Never treat such help as a waste of your time (because it’s their job) — they’ll surely pay the favour back sooner or later.
And if them is an open source project, then why not make a contribution? Your deed will help many others and your CV will thrive from all the glory — a win-win situation.
… and beyond code in general
Boy Scout rule stems from words of Robert Baden-Powell, founder of the world Scouting movement:
Leave this world a little better than you found it.
A little better. Making someone else’s day is enough. Remember about this next time you throw dirty dishes into a sink or use up the last bit of beans in the coffee machine.