Always leave the code better than you found it

Dear new developer,

I’ve spent a lot of my time maintaining working code. I think that is more typical of software developers than working in greenfield development. Yes, there are definitely jobs where you are writing more new code than maintaining, upgrading, bug fixing and improving old code (startups without product market fit being one, consulting being another) but in general code is expensive and folks want to run it for a long time.

Often you’ll jump into code to fix a bug, investigate an issue or answer a question.

When you do so, improve it. This doesn’t mean you rewrite it, or upgrade all the libraries it depends on, or rename all the variables.

You don’t need to transform it.

But you should make it better. Just clean it up a bit. Doing so makes everyone’s lives just a bit better, helps the codebase in a sustainable way, and assists the business by making its supporting infrastructure more flexible.

What are some ways to improve the code when you are in it?

Document

Whether that is a comment that explains something tricky, a larger piece of documentation external to the code which explains how to interact with it, or fixing a typo, trustworthy documentation is key to interacting with code. This is a good way to start improving a codebase because it has minimal impact on the actual code. Therefore it is low risk. But if you’ve ever had a great comment explain a confusing bit of code, you’ll appreciate the time this effort can save.

You can also help documentation by removing old, crufty docs. If you see a comment that doesn’t apply, remove it. If there’s cut and paste documentation which doesn’t apply, get rid of it. That cleans up the code for the next person to come along (who might be you).

Write a test or improve a test

Tests help you write maintainable, extensible code that others can change fearlessly. If you run across code that isn’t tested and you have time and the supporting framework to write one, do so.

Even if it tests simple functionality such as “can I instantiate this object” or “how does this function react when I pass it two null values”, an additional test will help the robustness of the code.

Refactor it

This is one of the most flexible improvements. Refactoring code can range from renaming a variable to be more true to its nature to an overhaul of an entire module. Start small and don’t get wrapped up in perfection. Make the code clearer in intent.

It’s easy with refactoring to get wound around an axle and make too many changes and end up with broken things. Timeboxing is one technique I use to avoid, or at least minimize, my tendencies toward this when refactoring. If all I have is 30 minutes, I’ll make my changes smaller in scope.

A warning about refactoring. Don’t refactor what you don’t understand. Don’t drive by refactor. Discuss your plan with someone more familiar with the code; git blame is your friend. Especially if the code is not well tested, you want to make sure you don’t do more harm than good.

Upgrade a dependency

It’s sometimes a winding path, but upgrading your dependencies regularly is a good way to maintain the code. I remember working in a fork of struts. It was an important application for the company, but we didn’t spend the time upgrading the dependencies, because it was too painful. Eventually, parts of the code became harder to update. The entire application couldn’t benefit from newer technologies and paradigms because of the older dependencies holding it back.

It never feels good to spend time updating a dependency; to me this always feels like running in place. But if you don’t do so, eventually dependencies will end of life and you’ll be forced to update. That’ll be even less pleasant.

How to do it

Based on feedback (this comment, among others), I added this section on Nov 28.

When you are making these changes to improve the code, you’ll help out code reviewers and your future self by making changes that are improving the code separate from changes that add functionality. Whether you do this in separate pull requests, tickets, or commits depends on your team culture. Ask about that. But such separation will make it easier for people who aren’t familiar with the changes to understand them and give feedback on them, whether that is a code review this week or someone reviewing this component two years from now.

Why do it

All of these actions not only help others because they improve the quality of the code, they also provide examples to other developers on how to do so. For example, it is far easier to write the second test in a suite than the first. You can cut and paste a lot of the setup code and tweak only what is different. The first bit of documentation will inspire more.

Code isn’t everything, but it is an important work output. Whenever you touch it, you should strive to leave it in a better place that it was before you did so.

Sincerely,

Dan

Read the documentation

Dear new developer,

Reading the docs is so important. It is so easy, when you are confronted with a task, to just jump in and start doing. It feels right. It feels natural. It feels like progress.

The problem is that it may be motion, but it probably is not progress. You may be spinning in circles rather than moving towards your goals.

So, the solution is to read the docs. Documents are key ways of transmitting knowledge and will let you reduce effort or reuse solutions. There are a couple of different kinds of documents that are worth reading:

Requirements/high level project docs: These are typically written specifically for the project, and will help give you a sense of direction. It will help you find how the work you are doing fits in. Depending on the size and maturity of your organization, you may find these documents in various levels of detail and completion.

If you don’t find any at all, take the time to write one, even if it is just a one page overview that answers “what are we trying to accomplish”. Send this to a senior member of your team (or of the business, if there aren’t senior technical team members) and ask “hey, did I document what we are trying to accomplish here?” If not, revise until everyone is on the same page.

Writing down these requirements can save tons of time, as they can bring new members of the team up to speed as well as bring the current team into alignment. If you are working on a project with human interaction, clickable prototypes can also be useful in determining the functioning of what the team is building.

Try to keep these documents up to date, though that is always a struggle. Whenever I start a new project, these type of docs are the first thing I look for, and if they don’t exist, I start writing them. They can take many forms and can include things such as overarching goals and terms (especially if they are not common vernacular).

Even a paragraph in Slack pinned to the channel is better than nothing, but I typically like to put them in a google doc (if the keeper of the doc is non technical) or a readme in git (if the keeper of the doc is technical). Having these kind of docs available will keep you from heading down errant pathways that aren’t moving toward the end goal. It reduces your effort.

Platform and library documents: These are user manuals for the tools you are going to use. Oftentimes they’ll be provided by an outside source (an open source project or a company) and are general in nature. As a new developer, hopefully you’ll have some internal guidance on these tools (even if it is just a conversation on why language X was chosen). But no matter how you arrive at the platform/library/framework, it’s a good idea to learn as much as you can about the tools you are going to be using. I tend to bounce back and forth between experimentation and documentation, but please find the learning style that works for you.

A thorough read of the docs will save you time. Recently I was using a snap in CMS for Ruby on Rails, a web framework. I wanted to customize the back end system and jumped immediately into prototyping code. Later I was reading through the docs and saw that there was official support for my customization. I burned a few hours of time figuring out the wrong way to do what I accomplished, then had to spend more time doing it the right way.

One of the difficulties of reading these kind of docs is sometimes you don’t know what you need to know, nor how to look for it. I can think of a few times where I was working in AWS. I scanned the documentation and got to work. Later, running into an issue, I went back and re-read the documentation. Lo and behold the solution to my issue was in the documentation, I just didn’t know enough to know that I needed that knowledge. There’s no way to avoid this. But having scanned the documentation for the tools you are using to solve your problem make you aware of any pre-built snap in solutions, and also may point out extension points that you’ll want to be aware of as you build out your solution. Reusing code and concepts will save you time and/or money.

However, don’t spend too much time reading docs and thinking about the problem(s) you face. I’m often confronted with a problem that is newish, whether in a domain that I’m unfamiliar with or combining two or more existing pieces of software in a novel way. Sometimes there’s no way forward but to just start thinking and coding, and documentation is no guide.

Knowing the bounds of the problem and information about the tools you have to solve it will help you determine when you are in a new space, and when and where you’re on well trodden ground.

Sincerely,

Dan Moore