How to review code written by an engineer better than you

Doing code reviews is mostly about spending thoughtful time reading code. Sometimes people focus on what things should look for during a review, and there are plenty of suggested checklists out there, or you can look at other code reviews among your team and make a checklist by paying attention to the patterns. This one habit will get you through most normal code reviews.

I think it’s easy to review code of someone who is new to a language. They may not write idiomatic code, or they may misuse certain language features as they learn a new language. If you know more than them about the language, the review is easy.

It’s also mostly easy to review the structure of the code for logical arrangement — for example, are objects and data models and abstraction used in reasonable ways? Are there reasonable interfaces? Is there reasonable defensive programming and error handling? If you are thoughtful about each of these areas, the review is easy.

Whether or not the code changes as a result of the comment is not what make a comment valuable.

It’s even easy to review code for functionality…check it out and attempt to run it.

Are some engineers better at each of these things than others? Yes. Some people are experts in languages. Some people are experts in modeling. Some people are experts at writing automated tests. Different people are good at different things. Some people are good at lots of things.


Every engineer is composed of different strengths, and for ease of discussion, let’s assume there are 100 dimensions to being a good engineer. Most good engineers are probably strong in about 70 of the traits, and part of the value of a balanced team is that everyone has a different 70, and once you get a certain number of people on a team, the team has strengths in all 100 dimensions.

But what happens when you’re a normal, even above average engineer, and you’ve got to review the code of one engineer who singlehandedly has at least 95 traits out of the 100? What can you possibly tell someone who is just objectively a better engineer? Why even bother? They’re probably right anyways…


Any really good engineer knows they’re good. So do the people around them. This isn’t about ego, there’s usually just a gentle acknowledgement. A really good engineer is obvious to everyone. The unexpected side effect is that sometimes this results in the really good engineer not getting feedback on their work, because everyone has the same impression — they read the code and go “hey this passes my checklist, but of course it would…approved!”.

This is unfortunate, because I think virtually everyone who is good at something enjoys it when someone takes time to engage with their work and provide commentary, good, bad, or neutral. It’s not as much fun to get rubber stamp approvals. No one is accidentally a good engineer — if they consistently produce quality, it’s because they’re putting thought into their work.

As a result, I try to leave some type of comment every time I read a PR. Sometimes I’m reviewing code where the author has more domain experience than I do, but I’ve found some techniques that help.

One of my best techniques is that as I read through the code, I leave comments like “So in this method, you’re basically….” or “Is this because….” Essentially, I just write down observations and questions. There’s no attempt to “give feedback” per se, it’s more like I’m validating that I was able to understand their code.

This is a crucial step.

There are lots of things you can have an opinion on, and it’s better to post something than nothing. Even a “simple” observation is something that even the most junior member of the team can post.

Whether or not the code changes as a result of the comment is not what make a comment valuable. The goal should not be to only post comments about suggested changes. The goal is to have a discussion about the code. Posting a simple observation, almost “restating” their implementation in a sentence or two, can be a valuable thing.

When someone gets comments on their work, it makes the author feel good that someone’s paying attention, and it also adds an important validation step. By explaining your interpretation of the code, you’re validating that it can be maintained in the future. You’re also contributing to documentation. Years in the future when someone is trying to understand something, and they jump back to the PR, they see the discussion and can validate their own understanding. This “verbal confirmation” can be deeply valuable to you and to other people on your team.

Put another way, code written by a senior engineer shouldn’t only make sense to other senior engineers. Part of what makes a great senior engineer is that they produce solutions that are maintainable, which means that even a more junior engineer should be able to understand it.

I think this is really the core spirit of “how to give feedback to an engineer who you know is better than you”. Even if you don’t have a “critique” of something, you can add value by doing nothing more than add comments that just explain what the code is doing, or that explain your interpretation of it.


Before you start the review, think about the functionality and come up with a 60 second guess as to how you’d write the code. This will give you a starting point. You’ll have a perspective (even if it might be incomplete) and then you’ll find it easier to add comments like “why did/didn’t you do it this other way?”. This comment pattern is a gold mine for fostering a good discussion.


It’s worth your time to do reviews. At minimum, you become a better engineer by reading code. If you know a piece of code was written by someone whose skill you admire, why not take the opportunity to study it? And if you study it, why not write down what you take away from it? This is what starts a discussion, and this is where learning happens. Plus, it helps the author. It’s just good all around.


If nothing else, add comments of things you thought the author did well. If this engineer is as good as you say, compliment what you think they did well. Maybe they’ll even respond with some more “yeah I thought this would be a good idea because X” and they’ll even have some other reason you didn’t even think about, and then you learn even more. Again, the goal is to have a discussion about the code.


My overall point is that there’s basically always something you can write on a PR, no matter what kind of skill difference there is between the author and reviewer. The point of code reviews is not just finding bugs, or fixing problems. There’s always some kind of discussion that you can have to break down silos, improve understanding, and improve your individual skills as well.

Politics and people

I’ve noticed I seem to have a different take on politics and people than most people do. I think there are a few books that I’ve read which have shaped my thinking. I wasn’t necessarily trying to learn about politics when I read them, I didn’t read them in any specific order, and they’re not really political books either. The ideas in them just seem to come up a lot.

The first book is Society of the Spectacle, which is a mind-blowing book. It was written in 1967. I don’t read French, so I read the English translation. It’s the sort of book where you make it through a sentence and you genuinely have to stop and think about what you read, not just because the ideas themselves are interesting, but you constantly have to stop and think about how it was written in 1967 and you think about the past 50+ years. There’s a digested version if you want.

Society of the Spectacle practically predicts social media, Instagram, cable news, “fake news”, and more. I think it goes beyond that in predicting things we can’t see like the phenomenon of clickbait headlines, information/filter bubbles, and addictive technology like that described in Hooked (and also predicting the followup, Indistractable). I think it’s worth really considering how these things affect politics and how we talk with each other as a nation.

On the “fake news” subject, Amusing Ourselves to Death nails it. I read this in 2003, and I know this because I liked the book so much that I looked up the author, Neil Postman, only to find out that he had died the week before. It’s never cool to find out about a new band right before they break up.

If you’ve spent any amount of time thinking about fake news and the problems with entertainment-as-news, you should read Amusing Ourselves to Death. It’s similar to Society of the Spectacle, but is much easier to read.

This next one isn’t exactly a book, but more of a subject area: Semiotics. This is some of the most mind-bending stuff of all. The official explanation is that semiotics is the study of signs and symbols, but this doesn’t do it justice. The best way I can explain it is that it’s about how Sherlock Holmes sees the world. It’s almost like a book that’s not about the meaning of things, but how things could mean anything in the first place.

I think semiotics is a foundation for Society of the Spectacle and Amusing Ourselves to Death. Knowing how we create meaning for ourselves seems useful in thinking about how the media affects us. I personally bought an introductory textbook, but there could be better books out there. For me, a big part of the point is about how people interpret the same thing differently, which happens all the time in politics. It seems to require a very careful separation of opinions and facts, and semiotics seems like a way to unwind these.

Onto a different subject with Thinking, Fast and Slow. It’s a book written by psychologists that won a Nobel Prize in Economics. That’s like winning in two sports at the same time — not easy. I think it even dips into being a sociology book in a way with discussions about what the authors call WYSIATI — our brains do a bad job at remembering, and I think this is worth keeping in mind when thinking inside our own heads, as well as when dealing with other people as individuals and as groups.

Another sort-of-a-book-but-really-a-subject recommendation is systems thinking. I personally read a book called Thinking in Systems, which covered the subject from an environmental angle, but is really useful when thinking about social programs and how we should think about trying to change things.

I’ll end this with one of my favorite things Obama ever said. This is solid, level-headed advice.

“Once you’ve highlighted an issue and brought it to people’s attention and shined a spotlight, and elected officials or people who are in a position to start bringing about change are ready to sit down with you, then you can’t just keep on yelling at them,” Mr. Obama said.

“And you can’t refuse to meet because that might compromise the purity of your position,” he continued. “The value of social movements and activism is to get you at the table, get you in the room, and then to start trying to figure out how is this problem going to be solved.”

“You then have a responsibility to prepare an agenda that is achievable, that can institutionalize the changes you seek, and to engage the other side, and occasionally to take half a loaf that will advance the gains that you seek, understanding that there’s going to be more work to do, but this is what is achievable at this moment,” he said.

https://www.nytimes.com/2016/04/24/us/obama-says-movements-like-black-lives-matter-cant-just-keep-on-yelling.html

Biden on judgement

When the subject of Trump came up aboard Air Force Two, Biden referred to a well-worn story about how, as a freshman senator, he saw Jesse Helms, the archconservative North Carolina Republican, ripping into a piece of disabilities legislation. Biden was furious about it and began attacking Helms to Mike Mansfield, the Democratic Senate majority leader. Puffing on his pipe, Mansfield asked Biden if he knew that Helms and his wife had adopted a disabled 9-year-old boy no one else would take. “Question a man’s judgment, not his motives,” Mansfield instructed.

I wish to hell I’d just kept saying the exact same thing – Joe Biden

Hard Work

I think this is a great representation of the hard work that goes into producing great results, and the lengths that it takes. This guy is working on a commercial for cereal, and to make sure that it looks good for the camera, he’s sorting pieces of cereal by hand.

I think that more often than we realize, great results are a matter of working hard at the most obvious stuff. Do you want a bowl of cereal to look good? Then sort through a few boxes until you have enough great-looking pieces of cereal to make a bowl. There’s no genius-moment-of-inspiration here, there’s no clever trick…just hard work.

Sorting cereal for commercial shoot

Time management for fathers

This is for the dads out there…

I read Getting Things Done years ago, and it had an immediate impact on my life. One of the tips saved me so much time each day that I decided to work out the savings over the course of my life. I found that with this one tip, I would save over two years of my life, a number that surprised me.

If a doctor walked into a room and told you they had found a drug that would, with no side effects, give you an extra two years of quality life, they would be hailed as a hero the world around. As a result, I’m always keeping an eye out for ideas that might help me get a happier, healthier, and more productive life.

I recently had my first kid, and while being a father is awesome in many ways, a child does require a lot of time, especially in the first 5-6 years. I quickly found that there were some ways in which I wasn’t making the most of my time.

I want to clarify — I don’t mean “making the most of my time” in an unpleasant sense of “grinding maximum productivity out of every moment”. Sometimes making the most of time can include drumming, watching TV, going for walks, or playing games (have you seen the new Arkham Knight?). These things are considered by some to be wastes of time, although there is a material benefit to them if they bring you joy. Even Steve Jobs went home and sat in front of the TV.

Given that being a parent has many unique constraints, a new book caught my eye that seemed like it might be relevant to me. The thing that surprised me a bit was that it was a book written for women: I Know How She Does It.

To me, there are many similarities when it comes to women and men who are trying to be successful in business and in their personal lives, so I decided to read it. I’ve got to say, it’s worth a read, even for men.

Any sociologist will tell you there’s a difference between how people self-assess their own behavior when compared to a more objective measurement. This is what made me so interested in this book. The author, Laura Vanderkam, gathered time logs from a large group of women who were both mothers and successful in their careers.

These time logs are recorded by her subjects every 30 minutes during their days, of what they were doing during that time. There’s no right or wrong here, just simply recording what it was. This is far more objective than anecdotal stories of how people spent their time, and in some cases, the women keeping the logs were surprised to find out how they spent their time.

Laura then takes this data, and presents her analysis of it, as well as some great case studies that both support her conclusions, as well as giving the reader an opportunity to mirror the techniques.

I don’t want to attempt to reproduce the contents of her book here, only to share how fresh and valuable I think her approach is, in taking hard data and applying it to the question of how to live a happy and productive life as a parent, for mothers and fathers.

When a jack of all trades wins

Everyone knows the expression “jack of all trades, master of none”. I remember a talk by Adam Savage of Mythbusters, where he brings that phrase up, and says that the real phrase is “jack of all trades, master of none, though often better than a master of one”.

During the 90s, the term “T-shaped individual” became popular, and the tech industry fell in love with the concept. The idea there is that while a person might have a wide breadth of skills in many areas (the horizontal part of the T), there is one area that they have deep knowledge of (the vertical part of the T).

Technology and business are areas where I think being aware of (and respecting) other areas of expertise is important, because it’s possible to go very, very deep. It’s impossible for one person to be really deeply aware of all areas. To me, the solution is to cultivate a respect for other domains. A sign of someone who deeply respects other domains is that they try to build relationships with experts in those other areas.

This came to mind the other day, when two different articles popped up on my radar. One was about integrating salespeople into the rest of the business, and the other was about how designers need to understand the full depth of a business, and not just make nice looking pictures.

It’s all too easy to shoehorn a business function into “just do your task and don’t worry about the rest”. Unless you’re exceptionally world-class at one skill (and even then!), it’s worth being mindful of the others.

When Keeping It Real Goes Wrong

Hat tip to Chapelle.

Well, there was a lot I didn’t know 10 years ago. The decision…is in keeping with a post-Boomer ideology that values emotional fulfillment above all else.

from http://www.theatlantic.com/magazine/archive/2011/11/all-the-single-ladies/308654/

The trick now is to subtly demonstrate that while you may have a job, a family, and a house full of stuff, you are not spiritually connected to any of it. What matters now is not just buying things, it is taking time for you, to create a life focused on your unique needs and that reflects your particular taste and sensibility.

from http://www.overcomingbias.com/2014/12/the-next-status-game.html

Ms. Bédat says people love being a part of an authentic brand because they aren’t just buying into a logo — but also “buying into a set of values.”

from http://www.nytimes.com/2014/12/28/business/quenching-consumers-thirst-for-authentic-brands.html?src=me&ref=general

Also, I still cannot believe that Tito, of Tito’s Handmade Vodka, is actually “Mr Beveridge”