You’ve written that final line of code and are pretty sure it should work now, you run it to double-check the code does what you were aiming to do, aaaand… It works! Yahoo! You did it! Now it feels like a good time to commit, push for review, sit back, breathe out, celebrate a bit, and jump to the next awesome feature in your long list of fascinating ideas! But wait for a second, there might be a few more things that would be nice to do before you ship your solution.

First of all, congrats! You wrote a code that works! This is a necessary step in the process of creating software, yet not the final one. 

There is a nice post titled “Always do extra”. Although it’s focused on mastering hard skills and growing the expertise, the idea that outstanding developers always do extra steps resonated with me. Here I’m sharing five more steps great developers take after their code works.

1. Take care of the readers

Good product leaders know their customers and care about them, good writers know and care about their readers. There is a lot in common between writing and software development, so good developers know and care about their code consumers.

Any fool can write code that a computer can understand. Good programmers write code that humans can understand

Martin Fowler

That quote clearly states there are two types of consumers of your code: computers and humans. While the code you just created can be successfully digested by a computer, it works after all! Can you tell the same about other developers? Will they understand your awesome idea? How much effort is required to understand your solution?

Those are great questions to ask yourself. In most cases, software development is a team sport. You’ll improve code written by your fellows, and they will build on top of your solutions. Chances are high there are different players in your team with different skills, experience, and domain area knowledge. So it’s time to make sure the code reads well by people with different backgrounds. 

Although it may sound simple there are many things under that cover and it’s not about code style or prettifying its look, I assume there are linters and formatters already in place to automatically make sure team agreements about code style are followed. There are things like naming variables and methods, commenting on unobvious solutions or decisions, extracting pieces of functionality into reusable functions, applying the right design patterns, and many more. If you’re not familiar with those I’d recommend starting with Clean Code by Robert C. Martin (aka Uncle Bob).

If you already know the theory and have experience in making code readable, here is the tip from professional writers – take a pause before starting code cleanup and switch to something else for a while. When you get back you’ll be able to read the code with fresh eyes and more effectively spot areas for improvement.

2. Respect other contributors

Unless you just started with a clean project, the enhancement you made is not the first one to be shipped. So the reasonable question to ask yourself is are old features working after my change? I doubt your fellow developers and precious users will be happy to discover one day that the feature they love and successfully used yesterday doesn’t work anymore.

To answer that question you’d need to run some tests. How you do it depends on the state and size of the project, the specifics of the code changed, available tools, the overall dev process, and some additional factors. 

In the best case, you have a good continuous integration pipeline (CI) with a decent set of automated tests that will run every time changes are pushed into the repository and the merge will be blocked if at least one of them fails. However, even if you have them you can save your time by running locally a subset of the automated tests covering the areas of the code which might be affected by your change. This will save you from getting back to the code after CI catches some mistakes for you. But it is worth doing only if the time and effort to launch the test environment locally is relatively small, otherwise, delegate this task to CI.

If you’re not so lucky and don’t have a good CI, there are at least two things that would be nice to do. First – try to run all automated tests you have or at least test critical paths of the project which potentially might be affected by introduced changes. Second – start talking to your team about the values of CI and automated testing, you may find a few good hints in this post.

3. Protect your solution

No matter if you were lucky or not on the previous step, I hope you see the value of CI and automated testing. So it’s time to make sure your own code has some protection.

The first kind of protection – automated tests – is needed to signal other developers if they unintentionally break your code. Depending on the scope of the feature, its importance, and complexity you might need unit, integration, end-to-end tests, or a mix of them. There is no single right answer on how much and which tests you need to write, you’d need to decide on the right balance of those yourself. Ideally, tests for the happy path, some expected unhappy paths, and maybe edge cases would be added. Doing so also highlights that those unhappy paths and edge cases were taken into consideration.

Tip: thinking about how to test your code early in the process leads to less coupled and better-structured solutions. Read TDD by Example book for more thoughts and examples on this approach even if you are not going to follow the test-driven development process. 

The second kind of protection – error boundaries – is needed to prevent the whole application from exploding if there is a mistake in your code. Depending on what are you working on this kind of protection might be not needed, e.g. if unhandled exceptions are a necessary part of the solution. However, consciously thinking through them and adding or not adding catchers where necessary is worth doing.

4. Add extra clues

There are good chances that the solution you’ve just made will be used not only by developers in your team or other teams in your org, and in the case of a popular product, there will be lots of people relying on your code. So it’s worth taking care of them as well by writing some docs, creating demos, or any other hints which would explain your solution from the product user perspective.

For example, QA folks would be happy with testing instructions to reproduce and test new changes, and end-users would be happy by getting up-to-date instructions in the product docs. Community members could benefit if a new library feature is listed in the docs with a good demo of how to apply it. 

In many cases, this step might be not needed, but creating a habit of taking a pause and thinking about it will positively impact the product. People will love your solutions and product much more if it’s clear and easy to use them.

5. Take care of reviewers

We are humans and we’re not immune to mistakes, that’s why the code review process exists, and hope you have it in your team as well. Taking some steps to help your reviewer will make the process faster and more efficient.

Here are a few things to consider:

• Commit messages.
• PR description. 
• Find and ping the right reviewer.

Let’s start with commit messages. Good commit messages are a valuable source of useful information for the reviewer. Those are hints and a history of work progress on the issue. So worth reviewing them before pushing changes to the remote repository and editing where necessary. Interactive rebase is your best friend in this process.

PR description. It is usually the first thing reviewer will read to understand what’s the PR is about. They have plenty of their own work to do so it’s naive to assume that PR reviewer always has the same or more deep knowledge of the issue you were working on. Despite that lots of information could be derived from commit messages, PR description is an important element to onboard a reviewer. It’s a good idea to have a clear and concise title of the PR, a link to the issue it fixes, a short description of main changes introduced, testing instructions to run/reproduce old and new behavior, screenshots in case of visual changes, links to designs and other important discussions where key decisions were made, and so on. The key point is to save the reviewer’s time searching for all of this info to understand your work and properly review your code.

Once your PR is ready for review, the final important step towards effective review is to pick the right reviewer. Unless this process is fully automated or documented in your team you’d need to make a decision here as well. Hope by that time you have a good understanding of which parts of the codebase are affected by your changes, so requesting a review from a teammate who is familiar and knowledgeable in that domain is a good idea. Taking reviewer experience into account is also important, e.g. it would be an arguable choice to ask a new or a junior developer to solely review complex change affecting many parts of the codebase. Sometimes asking two or more people to review the changes is reasonable, especially if those are critical ones.

---

If you’ve done all the steps above, you must be in a good position! Go ahead and send your awesome change for the review! You’ve done a great job by taking those extra steps, however, that’s not the end of the journey yet. The code review is a really nice and interesting process and deserves its own story.

In the end, I want to share a great quote made by WordPress one day – Code is poetry. It’s not a coincidence you’re called an author even if you don’t feel like a traditional writer at all. No matter if your code is a poem, novel, short passage, or anything else, you have the readers! And it would be nice to think about them and love them as I do now while writing this post! 

Take care of the consumers of your code!