The Boy Scout rule

Morillas — Fri, 04 Oct 2019 09:19:32 +0000

You are in front of that class and you start sweating. A switch which is not needed, unused legacy code, several blocks of code repeated, a condition based on a variable which never changes the value… and other things that usually appear in your worst nightmares. Probably sound familiar to you?

I’ve been in this situation recently. The code was not only mine, but even it was from a different project I’m working in. I’m collaborating with another project and I got to add some new improvements and features to an already existing one.

And I was there, in front of my computer thinking “Oh, boy, this is a mess. I don’t know where to start from”. “Should I refactor this code? Made it more readable and maintainable?”, I wondered. This is not even my project. How is the team responsible for this code going to take if I change completely the code?

And then I remembered the Boy Scout rule.

Apparently (and I say apparently because I’ve never been one), Boy Scouts have one rule which is that every time they go camping or in a group trip they need to leave the place tidier and cleaner than they encountered it (something not so difficult seeing how disrespectful and dirty people are)

And so for the code. For us developers, the Boy Scout rule means that you must leave the code you better than you found it. Probably a bit cleaner, probably with more tests, probably with better naming,…

Bad code sometimes is inevitable. We code a pretty decent first version of the code but then it comes issues fixed, patches, new features not considered in the first design, different developers with different styles,… and that decent code someone implemented in the first version becomes something difficult to read and maintain… and you wanna cry.

When it’s too late we need to allocate some time of the project to remove some Technical Debt. That’s when the Product Owner is not happy, and the Business Manager is not happy, and… only developers are happy. Because technical debt doesn’t add direct value to the product.

That’s when it comes the Boy Scout rule. If we apply it every time we have to add new code to an already existing one we contribute to a better and cleaner code. Probably to allocate less time in technical debt, and most probably to happier Product Owners.

If everyone is happier and the code is more maintainable and readable, why not apply it more often?

By the way, I refactored the code and the other team thanked me for improving it. They knew this code needed a huge refactor.

Don't document your code. Code your documentation.

Morillas — Wed, 25 Jan 2017 22:02:08 +0000

This is one of the great discussions among developers: document or not document your code? Is it worth writing documentation in your code?

I thought this topic was completely overcome and it was clear that, except some few occasions (implementing a public API), documentation was not necessary. Until I saw a code review where the reviewer pointed out the lack of documentation as an issue. Really?

I was one of those who used to document my code... or at least I tried. I was so convinced that code had to be documented. As a backup or reminder for my future myself or any other developer luck enough to end up in my code. Although I always realised it was always out of date. And by then, I already wondered: what is the purpose of documenting the code if the documentation is always outdated?

Until several years ago I read the book Clean Code.

I saw it "crystal clear", there is no need to document your code if you code your documentation.

With this I mean to use meaningful variable and method names. If the name of the member already tells you the information that is keeping and the name of the method tells you what the method is doing you can end up reading the code without the need to figure out or document what your code is doing.

Extract as much code as you can to methods. Even if you end up having a method with only 3 or 4 lines. Each method should do one thing and only one thing. And the name must explain what it does.

Each member of a class must have a name that only reading it you know which information you can find there. Same for variables and input parameters.

Following this simple steps you can have a code you can read, having the documentation right in the same code.

Yes, I know, there are those times you have to implement code with a complex algorithm or you are copying a code you found on Internet which might be complex, you might not understand and you might not extract in simple and meaningful methods. Yes, there are always exception.

What do you think? Do you document or write the documentation in your code?

This post was originally published in Medium

DEV Community: Morillas

The Boy Scout rule

Don't document your code. Code your documentation.