About the author
Will Barrett is a Software Engineer, Technical Lead, and Engineering Manager from the San Francisco Bay Area with over 14 years of experience. He’s a Superset PMC Member of The Apache Software Foundation. He’s held staff software engineer and senior engineer roles at Change.org, Entelo, Sqwiggle and Preset.
Will is the author of On Learning to Program, a blog for new Software Engineers entering the industry. Will is also a certified reviewer on PullRequest where he’s caught hundreds of bugs and other critical issues for over 30 teams.
There’s a particular moment in the development cycle that I get a lot of value out of. It’s the moment when I open the diff view on GitHub and go to create a pull request. In that moment, I’m able to shift my perspective from being the author of that code to seeing it as a reviewer would. Generally I catch at least 2 issues in a small pull request at this stage.
Why is Cognitive Shift is Important for Development?
As programmers, we are generally biased when it comes to our own code. We understand our own reasoning clearly when we create a piece of software - our own minds created the reasoning! Typically we tend to look at our own work with less of a critical eye as a result. When we are in our own text editor, on our own computer, with our standard fonts and syntax highlighting it can be hard to see flaws. Seeing our work in a different context allows us to distance ourselves from it slightly. This is why authors will frequently print out their own work to read and mark up with a pen - shifting away from the computer allows for a different, and more distant point of view.
How to Encourage the Cognitive Shift
I find it’s helpful to pause right before I’m about to open the pull request, stand up, have a drink of water, or do something else for a few minutes. Creating a pause and distracting myself before looking at the code I’ve just written in a different context helps me gain distance from it. For larger PRs that aren’t subject to an urgent deadline, sleeping on the code can also help. I also like to make sure that my editor and terminal configuration look substantially different from GitHub’s - I use GitHub’s light mode, but in my editor I use a dark mode. I use a different monospace font with ligatures. And I use a different format for diff viewing between GitHub and my local config. I see different things when looking at a split diff vs. a unified diff.
What to Expect
I find a lot of silly mistakes when reviewing my own code. My most common error is finding log statements or debugging code that I haven’t reviewed before committing and pushing up. I also find a disheartening number of typos. Frequently when I see my work in a different context it also becomes obvious what sections of the code are too complicated, and frequently decent refactors occur to me at this step.
When I Feel Uncertainty
Typically when re-reading my own code in a different context, I’ll have a reaction that is best described by the
:notsureif: emoji 🤔. Is this right? Did I do that correctly? Is that logic really doing what I think it is? Is this
the best approach? This feeling typically encourages me to do these three things:
- Write more automated tests to check myself.
- Play with a bit of functionality just to be sure before opening the pull request.
- Ask a question to other reviewers as a comment on my own code.
I consider all of these activities virtuous, and they arise from reading my own code in a different context.
When I Feel Fear
Occasionally you’ll have a really scary, boy-I’m-glad-I-caught-that moment. Reviewing my own code has kept me from opening pull requests that could result in data loss, errors, performance bottlenecks, and all manner of other bad outcomes. It’s possible these issues could be caught by other reviewers, but in many cases it may not work out that way - after all, the person most familiar with code is the one who wrote it. When I self-review my own code the biggest value I get from peer code reviewers is insight into the things I don’t know or effective approaches I was familiar with prior.
Go Forth and Self-Review!
I hope this has convinced you to give self-review a try, and lean into the moment when you’re just about to open a pull request. There’s a lot to be learned from really reading one’s own work in a different context. It certainly has made me a better programmer.
Find this useful? Be sure to check out these additional articles by Will:
