Leave Code Better than You Found It

I am grateful for my experience in the Boy Scouts and thankful I was able to make it all the way to Eagle Scout. While everything wasn’t perfect (like anything else), I learned invaluable lessons about leadership, teamwork, respect for nature, and survival skills. One of the recurrent themes involved in our outings, gatherings, and organization was “leave things better than you find them.”

It applied to the wilderness, where we would try to leave any camping areas we used (or created) cleaner than we found them to minimize our footprint and environmental impact. It applied to leadership, too. We were encouraged to help people grow, to make things better for each other and for those in the future.

The same principle — leave things better than you found them — should apply to development, too. You can help everyone (yourself included) by improving the quality of code that you touch. And if everyone makes this a regular part of their workday, your team or organization as a whole will pay down technical debt it has accrued over time. And then your company becomes a unicorn and happily ever after ;-)

Five Ways to Leave It Better

1. Make it shorter & remove cruft: The old TDD mantra holds: red, green, refactor. If you see an area of your code that has no reason to be there, get rid of it. Save sentimentality for everything else in life, but do not bog down your systems with useless code. Short code is not necessarily better code, but code that achieves it’s goals in the most minimal way possible usually is.

2. Make it make sense: We know that naming things well is really, really difficult. So, if you see code that’s full of for i in j, iOnPQRD, ackSysNetGo, change them. Also, be sure to watch out for naming conventions that introduce readability errors due to similarity. For example, names that only differ by a tiny character in the middle of a long name are going to be easily forgotten and introduce bugs.

3. Update comments: My general rule-of-thumb with comments is that they should really only be necessary to document a part of the API that is not easily inferred. For example, if I have a Circle class and a user wants to move that circle, something like Circle.move(direction) should make it abundantly clear what the method is doing and what the signature is. When they are needed, they can easily get out of date. Your helpful // don't forget to blah blah or # do not use might not hold true over refactoring and can be misleading to other developers…causing bugs!

4. Write a meaningful source control messages: Unreadable commits can be a huge frustration when you really need to look through your codebase’s history and track something down. Using git bisect <subcommand> <options> and other tools be really helpful in getting around this, but you will encounter trouble regardless if your commits are nonsensical.¹ So, make them meaningful. Group related changes together, write a good summary, include a compelling justification, and create a testing plan. Apart from being a good template to start with, there are other benefits to this sort of approach. It will let yourself and other team members 1) know what your changes are, 2) why they are needed, and 3) how you know they don’t break anything.

5. Enforce Linting & Syntax Styles: If you are working on a project and it is just you and a couple friends, you might not run into any issues with code style. But it is a virtual guarantee that you will on a larger team. In this situation, you really should just agree (e.g., leads and CTO should decide upon) a style guide and enforce it with automated linting rules and static analysis tools like ESLint. Not only will using a tool like this eliminate a many types of errors, it will save everyone the time of arguing over competing styles. In JavaScript, tabs vs. spaces, using semicolons, where variables get declared, etc.

Fin

I hope this has been en encouragement if you already try to improve the code you come across, and else-wise an inspiration to do so!

Happy hacking ¯\(ツ)/¯