Software Engineering Tidbits

Software Engineering Tidbits

Share this post

Software Engineering Tidbits
Software Engineering Tidbits
Code Reviews
Copy link
Facebook
Email
Notes
More
User's avatar
Discover more from Software Engineering Tidbits
Small (or sometimes big) tidbits about software engineering. This is where I share tips and learnings I acquired building, maintaining and supporting software in production at Airbnb, Uber and Microsoft.
Over 10,000 subscribers
Already have an account? Sign in

Code Reviews

All about code reviews from the author to the reviewer

Georges El Khoury's avatar
Georges El Khoury
Jan 27, 2022
18

Share this post

Software Engineering Tidbits
Software Engineering Tidbits
Code Reviews
Copy link
Facebook
Email
Notes
More
1
Share

Code reviews are one of the activities you will spend the most time doing in your software engineering career.

Unfortunately, it is not something software engineers learn in schools or are specifically mentored about.

Below is a detailed guide on how to conduct a code review from both the perspective of the author and the reviewer.

Author Perspective

  1. Keep your pull request small. This is the most important advice in this post. Large pull requests with a lot of changes are hard to review and are always punted for later. Once deployed, they are harder to debug, monitor and rollback. Similar to the one class one responsibility concept, aim to have your pull request also do just one change at a time.

  2. Have a structured outline. Start with a clear and concise title. This is what shows up in the git log. In the description, it is important to cover the below sections: What?, Why? + Context + Ticket, How is it tested? and Reviewers.

  3. Help the reviewer help you. Add screenshots if it is a UI or front end change, curl requests/responses if it is a backend change, and add line comments on code diffs when more context is needed. Show the reviewers that the changes have been well tested. This will give them more confidence to stamp and approve the PR

  4. Avoid having the PR grow in size. A lot of time reviewers would take the opportunity to ask you for a refactoring while you are touching a certain area of the code. This is a legit comment. However, doing the refactoring in the same PR will make it bigger and doing more than one change at a time. This is to be avoided at all cost. One thing you can do instead is promise to do a fast follow in a new PR to address the refactoring comment and make sure to really do it later to build credibility in your organization.

  5. Be open for feedback. It is possible for the most experienced software engineers to go in a blind spot or end up with a non optimal implementation. Having an open mindset and understanding the feedback provided in the code review will go a long way in improving the quality of the pull requests. Treat code reviews as gift rather than a burden.

Reviewer Perspective

  1. Do not auto approve pull requests. If you do not have enough bandwidth to deep dive on the pull requests and spend time understanding it and reviewing, do not be a reviewer. Auto approving with a LGTM (Looks good to me) without a proper review is worse than not reviewing at all. On the opposite side on this, do not be too slow to code reviews, answer comments, etc… The code author is most probably blocked and waiting for your stamp.

  2. Do not start reviewing unpolished pull requests. If you are going to spend time reviewing the PR, it should be ready and in a reviewable state. Make sure the PR is ready, small in size, tested and is passing the build before you start investing time in reviewing it.

  3. Be respectful and friendly. Put your comments in forms of suggestions and questions. Instead of saying move this logic to a new class say looks like this class is doing a lot. Should this logic be in a new class? This keeps the review friendly and constructive.

  4. Pay special attention to non reversible decisions. All code changes are important but pay special attention for things that cannot be reverted such as new endpoints, new dependencies, public methods, etc…

  5. Stamp with comments when needed. If you do not have a strong opinion on a certain comment or is a minor comment (usually preambled with nit), write it and then approve/stamp the PR. This will leave it up to the author discretion to either address the comment or not.

So what should you look for as a reviewer?

  1. Make sure the PR is readable. We can spend a whole chapter describing what is a readable code but the best definition I can come up with is a code that is glanceable and easily tells us what it does

  2. Make sure the PR is small in size.

  3. Make sure the PR is properly tested.

  4. Make sure the PR is doing what is supposed to do.

  5. Make sure encapsulations and abstractions are well designed. Are we exposing a property/method that we should not? Is a class or method doing a lot? On the opposite, is an abstraction/encapsulation unnecessary? Is the implementation overly complicated or engineered?

Code reviews are important for every software engineering and engineering organization. I hope you liked this guide. If you did, subscribe to this newsletter. I will be publishing similar posts on software engineering and tech startups.


Software Engineering from the Frontlines Course on Maven

If you liked this article, I will be teaching a “Software Engineering from the Frontlines” course on Maven where I will teach hard-learned lessons I acquired developing large-scale products at companies such as Uber, Airbnb, and Microsoft.

View Course


Thanks for reading Software Engineering Tidbits! Subscribe for free to receive new posts and support my work.


Angel's avatar
Nurfitra Pujo Santiko's avatar
Vincenzo Acinapura's avatar
Ali B's avatar
Julius Seporaitis's avatar
18 Likes
18

Share this post

Software Engineering Tidbits
Software Engineering Tidbits
Code Reviews
Copy link
Facebook
Email
Notes
More
1
Share

Discussion about this post

User's avatar
Ryan Peterman's avatar
Ryan Peterman
Mar 7, 2023

Areed that smaller changes are almost always a good thing. If a PR grows larger than I expected, I'll often break it down into several so it's easier to review.

Expand full comment
Like
Reply
Share
A good unit test
A good unit test should be:
Feb 20, 2023 • 
Georges El Khoury
18

Share this post

Software Engineering Tidbits
Software Engineering Tidbits
A good unit test
Copy link
Facebook
Email
Notes
More
5
A good way to debug
One of the best software engineering tip I received is a good way to debug.
Apr 28, 2022 • 
Georges El Khoury
16

Share this post

Software Engineering Tidbits
Software Engineering Tidbits
A good way to debug
Copy link
Facebook
Email
Notes
More
2
Outage Management
Outage management is a core skill for a software engineer to acquire and is critical to achieve high availability of an online service.
Feb 13, 2023 • 
Georges El Khoury
13

Share this post

Software Engineering Tidbits
Software Engineering Tidbits
Outage Management
Copy link
Facebook
Email
Notes
More
3

Ready for more?

© 2025 Georges El Khoury
Privacy ∙ Terms ∙ Collection notice
Start writingGet the app
Substack is the home for great culture

Share

Copy link
Facebook
Email
Notes
More

Create your profile

User's avatar

Only paid subscribers can comment on this post

Already a paid subscriber? Sign in

Check your email

For your security, we need to re-authenticate you.

Click the link we sent to , or click here to sign in.