Jake Worth

6 Tips For Reviewing Your Own Code

Published: November 12, 2022 4 min read

This post was inspired by the following Tweet:

You need a code review, but you don’t have another person.

Maybe you’re building a startup and there’s nobody else with the context to give you feedback.

Maybe your preparing a demo and want to refine your code before sharing it with others.

Maybe you just want to get better at programming by critiquing your own work.

First, bravo! Many developers don’t read their code at all. Reading your code shows you’re committed to quality.

Great developers review their code often and effectively. In this post, I’ll share six tips for maximizing this important practice.

Throughout, I’ll be talking about GitHub pull requests, or PR’s, a common medium for reviewing code. Apply these tips to however you review code.

Wait

Wait as long as you can before reviewing your code.

In On Writing, Stephen King recounts that when he finishes a first draft, he puts it away and doesn’t look at it for a long time. The closer we are to our work, the harder it is to criticize it.

So, get some distance. Even ten minutes helps. I like to open PR’s at the end of the day and self-review them first thing in the morning.

Ask “What Doesn’t Belong?”

To quote my colleague Josh Branchaud: “look for what doesn’t belong.”

What’s in the PR that shouldn’t be? This could be logging and debugging statements, abandoned ideas, and noise that distracts from the precise thing you’re trying to do.

We’ve all seen a PR that adds a new feature while also removing a single line of whitespace from a random file. As I wrote about in ‘When Should I Not Refactor’, these random cleanups often do more harm than good.

Pare it down to just the essentials.

Consider Scope

When you review your changes, do you feel overwhelmed by the scope? Break them into smaller pieces.

There’s a saying about reviewing code: “Show me ten lines of code and I’ll find ten improvements. Show me 100 lines… looks good!” It’s hard for anyone to give meaningful feedback on a huge PR. They are a burden on the team. Help others help you by cutting scope.

Consider Names

Names are hard and important. Make them good.

Do your names make sense? Do they reflect the language, framework, and team conventions you’re working with? If you saw the same variable names in someone else’s code, what would you think?

Make renames easy, consider your names, and change them when beneficial.

Consider PR Quality

Does your PR, as a deliverable, makes sense? Titles like “fix stuff” and empty PR descriptions don’t scale beyond one person. Here are some ways to know if your PR is comprehensible:

  • Does it answer what, why, and how?
  • Does it include a link to the ticket or design files you’re following?
  • Does it include references to prior art, like other PR’s?
  • Would it be better with a screenshot?

Your PR should have these things, because that makes it understandable and discoverable. Sure it’s in the Pivotal ticket, but lots of teams switch from Pivotal to Jira to Asana to Trello. Why not take a minute and explain your work close to the code? You’ll thank yourself later.

Add Comments

Preempt questions someone else might raise with comments.

I usually leave a few comments on my own PR to cement all the context I have at that moment. An example might be: “Note: I considered not logging this to Sentry, but we have no other way to know if it fails.” That’s a bad comment to put in the code, but I shouldn’t throw it away completely. It’s useful information that explains a questionable decision.

I try to use Conventional Comments even for my own reviews. “Note:” and “Question:” help clarify what I’m trying to achieve with the comment.

Extra Credit! Squash your Commits

An extra touch is to squash your Git commits. Some people read code by commit and it can be valuable context when well presented.

With the rebase tool in your belt, you can convert your commit history from a mess of “trying this”/“one more time” messages into a tidy menu of changes that make you look very smart. It’s a little thing! And yet, when I see it, I’m primed for a positive reviewing experience.

Wrapping Up

To summarize:

  • Wait as long as you can to review
  • Ask “What doesn’t belong?”
  • Consider scope
  • Consider names
  • Consider PR quality
  • Add comments
  • Squash your commits

How do you review your own code? Let me know in the comments.

Thank you to Josh Branchaud and Dillon Hafer for thinking about this with me.

✉️ Get better at programming by learning with me. Subscribe to Jake Worth's Newsletter for bi-weekly ideas, creations, and curated resources from across the world of programming. Join me today!


Blog of Jake Worth, software engineer in Maine.

© 2022 Jake Worth.