The Boy Scouts have a rule: leave the camp cleaner than you found it. This does not mean that all the trash has to be cleaned up now, but you can’t let it get worse, and it must get at least a little better. In Bob Martin’s book, Clean Code, he asks, “What if code got a little better every time you change it?” I’ll answer it: the industry would not find itself in the mess it’s in. The industry norm is for code to incrementally worsen with each change.
Much of the time, following the Boy Scout Rule won’t be hard. It’s an incremental strategy. It’s easy to start and easy to sustain. Here are some typical challenges and ideas on how to be a Boy Scout.
Adding to a Long Function
Extract something; there must be plenty of opportunities to pull out some idea and name it. You want to add 3 lines, take out 5. Net improvement leaves a function 2 lines shorter. But I bet you can easily do better. Fix another complex conditional nearby to start a pattern of improvement.
Adding to a complex conditional
Extract the conditional into a helper function. Name it and its parameters well. Write a few tests for it. That’s picking up the obvious beer cans.
Look at the extracted code carefully. Does the conditional really belong with some other module? If so, the complex conditional is likely to be duplicated and the newly extracted function should be moved. Do the work or add it to your technical debt list.
Copy/Paste/Tweak Temptation
You see a copy/paste/tweak opportunity that meets the functional requirements. Don’t do it, except maybe to test your hypothesis. Before, or after the change, do what the code is telling you: extract the common code into a helper function. Generalize and parameterize it so it handles both cases. Write tests around the code to be extracted to guard against breaking existing functionality. Make a list of the other previous cut/paste/tweaks of the same code for conversion.
Cryptic Local Variable Name
Once you figure out what the variable is for, rename it to help you, and your teammates, on the next code visit.
Deep Nesting
Pull out a nesting level or two into a helper function.
Broken Glass and Beer Cans in the Fire Pit
Put on some gloves. Clean out the big pieces of glass and cans. Bag the trash. A heavy duty bag is best. Be careful not to put any embers in the bag. Take the trash back to the boat.
Yes Jim…. However, typically leaving the campsite cleaner is merely picking up obvious “garbage” around you and maybe removing traces of your presence.
Most everything one typically does as a good conservationist/hiker/camper are obvious and have no downstream or otherwise impacts. That is, picking up a gum wrapper will never cause a cascade of other events.
Also, the “tests” are simply visual inspection and generally pretty accurate. Though some people are not as meticulous as others.
Code is not always so simple to inspect. Code may not always have the tests to ensure no downstream impacts. What’s worse, you might “clean up” a weird looking dangling piece of code. Only later to find it break some arcane aspect of the app a year later.
So, the real challenge. How do we make our code camp as simple and obvious as the campsite in nature?
What if you saw a pile of logs in the corner, serving no obvious purpose. They were however quite meticulously arranged. Do you tidy them up, or leave them?
If you tidy them up but didn’t realise it was a custom built habitat for frogs/voles or whatever, it means that you’ve inadvertently destroyed the home of some woodland folk.
Without good tests, cleaning up after other people is dangerous.
A pile of logs in a campsite? I’d have to have a fire 🙂
Pingback: Legacy Code Change – a Boy Scout Adds Tests « James Grenning’s Blog
If you saw meticulously, yet oddly-present, structure with no apparent purpose, then “cleaning up” would be to make the structure more obvious. As long as it is a mystery, someone is likely to misinterpret its purpose.
One might suppose it is free firewood and burn the vole or frog habitat. Another might consider it a mess to clean up. Another might see it as a seat, and squash poor froggy. Another might pile other things on top of the existing pile, again squashing froggy flat.
In some cases, making the mysterious pile an obvious habitat area is cleaning up the area. In code, this is often the thing we must do. When we don’t know what it’s for, leaving it unclear is the wrong answer.
The meticulously, yet oddly-present, structure with no apparent purpose, would be like code that needs a comment because it could not be made to speak for itself.
Pingback: Scrum Strategy – The Dev Team Improvement Backlog « The Scrum Crazy Blog
Pingback: A collection of links regarding Agile with a capital A « whygwarren