Chapter 9 of Software Engineering at Google Book Summary

Google’s Code Review Process

Dive deep into Google’s code review process with a detailed breakdown of Chapter 9 from “Software Engineering at Google.”

Reader guide of series

About the Book

Have you ever wondered what powers the technological giant that is Google? The key lies in their approach to software engineering, a subject masterfully dissected in the book “Software Engineering at Google” by the acclaimed Titus Winters and meticulously edited by Tom Manshreck.

In a rapidly evolving technological landscape, equipping yourself with the foundational principles of contemporary software development isn’t just beneficial; it’s essential. This book promises a wealth of knowledge to aid your personal and professional growth.

Why Read This Summary Series

As you tackle this learning journey, my series of detailed chapter summaries will be your guiding hand, helping you:

• Understand Google’s gold standard principles with ease.
• Engage in thoughtful discussions fostered through deep insights.
• Save time by getting to the heart of each chapter quickly.

Don’t just take my word for it; dive in and experience the rich reservoir of knowledge yourself. Find the complete summary series here:

What to Expect in Each Summary Article

Every article is based on a chapter of the book and offers:

• A TL;DR section for a quick snapshot of key insights.
• An in-depth analysis of the chapter’s core concepts.
• Conclusion to summarize the learnings.

The goal is to present you with an unbiased view as I focus on condensing the book’s key insights without injecting personal opinions.

Are you ready to journey into the depth of Google’s software engineering brilliance? follow me, subscribe to the newsletter, or contribute by buying me a book to support this series and fuel this voyage of discovery.

TL;DR

“Software Engineering at Google” in Chapter 9 unpacks Google’s rigorous code review method, which centers on enhancing code quality and promoting team collaboration. The systematic approach touches on multiple approval standards and hinges on a distinct ownership model. This method yields benefits like accurate code, easy understanding, uniformity, team benefits, and knowledge dissemination. Google emphasizes professional conduct, concise code edits, detailed change notes, limited reviewer involvement, and task automation. Furthermore, Google segments code reviews into various categories, each with distinct emphasis and criteria.

Introduction

Chapter 9 of“Software Engineering at Google,” by Tom Manshreck and Caitlin Sadowski and edited by Lisa Carey, demystifies the code review process at Google, a critical practice that ensures the maintenance of high code quality and fosters a collaborative culture. Code review is the act of someone other than the author examining a code before it’s added to the main codebase. The way code review is implemented can vary across the software industry. Some companies have specific groups to review changes, while others let individual teams handle them. Google requires every change to be reviewed before it’s committed, and every engineer participates in initiating and reviewing changes. Google uses a custom tool called Critique for its code review process, but this chapter focuses on the review process itself, not the tool. Code review offers many benefits, from catching bugs before they enter the system to other subtler advantages like psychological benefits, which become evident over time and with scale.

Code Review Flow

At Google, code reviews occur before a code is added to the main codebase, termed a precommit review. The main aim is to get another engineer’s approval, often indicated by “looks good to me” (LGTM). Here’s the typical process:

1. An engineer drafts a code change and captures a snapshot of it.
2. This snapshot is used for automated comments or self-review. Once content is received, the engineer sends it to reviewers for feedback.
3. Reviewers inspect the code and leave comments, some of which require action.
4. Based on feedback, the engineer updates the code and informs reviewers. This cycle can repeat several times.
5. Once the reviewers are satisfied, they mark the code as LGTM. Typically, one LGTM suffices, but sometimes all reviewers need to consent.
6. With the LGTM tag and all comments addressed, the engineer can commit the change to the codebase.

Code, while necessary, is seen as a liability. It poses a maintenance challenge in the future, similar to an airplane’s fuel adding weight yet is vital. Before writing new code, one should ascertain its need to avoid duplication and extra work. The sentiment at Google is that if you’re starting from scratch, you might be on the wrong track. Especially with utility code, there’s a high chance someone has already written something similar. Tools help find existing code and prevent redundancy. While new projects and components are inevitable, code reviews aren’t the place to challenge prior design decisions; those should have been settled before the review stage.

How Code Review Works at Google

Understanding how code review works at Google is like getting a master class from industry leaders. This section delves into the complex processes and standards Google engineers support during code reviews. Google’s code review process is meticulous and designed to ensure quality and maintainability. The review process is based on three key approval criteria:

1. Correctness Check: An engineer verifies the code’s accuracy and that it functions as intended. This is reflected in the LGTM endorsement.
2. Code Ownership Approval: The code must be suitable for its specific part of the codebase. Google’s codebase is organized hierarchically, and each section has designated owners. Only these owners, which can include tech leads or experts in that area, can approve code additions to their directories.
3. Language Readability Approval: The code must adhere to the specific programming language’s style and best practices. This approval ensures the code is consistent and maintainable across the company.

While this process may sound elaborate, it’s often streamlined, with one person performing multiple roles. For instance, if an author already has readability in a language and owns a part of the codebase, they only need an LGTM from another engineer to submit.

The primary benefit of this detailed review method is its flexibility. It accommodates everyone from tech leads to interns, allowing for a broad range of code submissions while maintaining quality. Typically, the process involves an initial review from a peer for code correctness followed by approvals from the relevant owner and/or readability reviewer. In essence, Google’s approach ensures that the code functions as intended fits within the broader ecosystem of the company’s codebase, and adheres to established coding standards.

Ownership in Google’s Codebase

Hyrum Wright discusses the concept of “ownership” in large-scale software projects. In smaller teams, everyone might have access to the entire codebase due to familiarity and expertise. However, as teams grow, this approach becomes inefficient. Google addresses this by designating “owners” for different parts of the repository, emphasizing their role as stewards rather than mere possessors of code. These owners are listed in specially marked “OWNERS” files, defining who is responsible for particular code sections. This hierarchical system means a file’s ownership can be traced through the OWNERS files in its directory tree.

Being an owner at Google means having the authority to approve changes in one’s designated code sections. Still, it also comes with responsibilities, like understanding that code or knowing who does. Google suggests that ownership shouldn’t be a mere initiation rite for new team members and that those leaving should hand over their roles promptly. This distributed ownership model, fundamental to Google’s operations, supports various other practices. For instance, root OWNERS can approve extensive changes without local team interferences. These OWNERS files also serve as a directory, guiding individuals to the right person for specific code sections.

Code Review Benefits

Many companies and open-source projects see code review as an essential check on new code. Google’s approach to code review is more detailed and widespread than others. Despite being a flexible company, Google mandates code review for nearly every code alteration, recognizing its importance even though it can slow down coding speed. The main advantages of a rigorous code review process include:

• Verifying code accuracy,
• Making sure others can understand the code,
• Maintaining consistency in the code,
• Enhancing team responsibility,
• Encouraging knowledge sharing,
• Documenting the review process.

These benefits are vital for the longevity and health of a software organization and benefit both the code writer and the reviewers.

Code Correctness

Code review ensures the “correctness” of new code. It lets another person verify that the new code functions as intended, is well-designed, and is efficient. The main objectives are to prevent potential bugs and ensure proper testing.

Early defect detection during code review reduces future bug-fixing time. IBM’s study highlights that catching defects early saves significant time in later stages like testing and debugging. However, keeping the code review process efficient and lightweight is essential to avoid it becoming cumbersome.

It’s important for reviewers to remain objective. They should prefer the original author’s approach unless proposed changes improve clarity or functionality. Swift approval of beneficial changes, even if not “perfect,” keeps the review process efficient.

Modern tools, like static analysis and automated testing, help check code correctness, reducing dependence on manual reviews. But human reviews remain crucial in ensuring quality. The primary goal isn’t just about finding defects early and ensuring that code is clear and maintainable. While ensuring code is “correct” is crucial, Google emphasizes making sure code remains understandable and scalable over time.

Comprehension of Code

Code review is the initial chance for someone other than the author to examine a change, offering an unbiased perspective. It tests if the change is clear to a broader audience, which is crucial since code is read more times than written.

Selecting a reviewer with a different viewpoint, especially someone who might work with the code in the future, can be valuable. Comprehension questions should be treated seriously, as clarity is essential. While you don’t necessarily need to change your approach based on feedback, it might require a clearer explanation.

Two main criteria for a code review approval at Google are met: the code is correct and understandable. It confirms these two aspects when marked with “LGTM.”

Code Consistency

When writing code, it’s essential to remember that others will depend on, read, and eventually maintain it. For this reason, code should be consistent and not overly complex, making it understandable and maintainable.

Reviewers check if the code aligns with the codebase standards during code review, ensuring the code’s health. Google separates the approval states of “LGTM” (indicating correctness and comprehension) from “readability” approval. Readability approvals ensure the code adheres to best practices for a specific programming language, remains consistent with Google’s codebase, and isn’t overly complex. Consistency facilitates tool-based refactoring.

Consistent code is read and understood more easily across the engineering team. It even benefits the code review process, allowing engineers from different projects to step in, review, and offer insights, knowing the code adheres to consistent standards.

Psychological and Cultural Benefits

Code review emphasizes a collective ownership mindset among software engineers, steering them from individualistic styles to a more unified approach. This process acts as a neutral and structured medium for feedback, reducing the chances of emotional confrontations. By framing the review process as the “bad cop,” the individual reviewer can be viewed as the “good cop,” offering critique without feeling personal. While newcomers might initially find the concept of code review daunting, over time, they come to value constructive feedback and even anticipate the challenges.

One notable advantage of code review is the validation it provides. It helps combat feelings of self-doubt, like the imposter syndrome and serves as a platform for mutual recognition and exchange of ideas. Furthermore, the act of initiating a code review encourages quality assurance. It pushes engineers to be thorough in their work, minimizing the chances of them cutting corners or postponing essential improvements. This process instills a sense of accountability, ensuring the code presented is as polished as possible.

Knowledge Sharing

Code review plays a pivotal role in facilitating knowledge sharing among engineers. Typically, authors select reviewers with expertise or a good understanding of the area under review. This setup allows reviewers to share domain knowledge, offer new techniques, or provide advisory information to authors. In some cases, comments are simply shared for informational purposes. Proficient authors often evolve into owners of specific code areas, further enabling them to review the work of other engineers.

A crucial component of the code review process is the feedback loop, where questions are asked about why certain changes were made in a specific way. This interaction encourages mutual learning. For instance, authors and reviewers can glean new techniques and patterns from code reviews at Google. Google’s platform even allows reviewers to suggest direct edits within the tool. Given the weightage engineers give to code reviews, this becomes a prime avenue for timely and actionable knowledge dissemination, transcending time zones and projects. Many Google engineers first interact with their peers through code reviews.

While programming remains the primary task for Google engineers, much of their time is dedicated to code review. This process emerges as a primary interaction and knowledge exchange point, introducing engineers to new coding patterns. Since code reviews are maintained as part of the historical record in the codebase, any engineer can trace back the introduction of specific patterns. Such investigations often offer valuable insights to a broader audience than the initial author and reviewers.

Code Review Best Practices

To excel in code reviews, adopting the best practices is non-negotiable. In this section, we delve into the best practices advocated by Google, offering readers a guide to mastering the art of code reviews.

Be Polite and Professional

Google strongly emphasizes a culture of trust and respect, especially during code reviews. One crucial takeaway from this section is the importance of politeness and professionalism throughout the process. Reviewers are encouraged to provide feedback promptly, ideally within 24 working hours, and to refrain from delivering comments piecemeal. Additionally, rather than assuming an incorrect approach, reviewers should seek clarity by asking the author questions.

On the author’s side, there’s a need to remain receptive to feedback, remembering that the code, once integrated, belongs to the team and not the individual. The dialogue between reviewers and authors should be constructive, treating each comment as a “TODO” item. Disagreements should be handled professionally, with both parties considering it a chance to learn. Finally, those overseeing codebases should be open to improvements suggested by external contributors, valuing the overall enhancement of the codebase.

Write Small Changes

For an efficient code review process, keeping code changes small is recommended. Google’s procedure encourages concise changes, focusing on individual issues for easy comprehension by both authors and reviewers. Large changes can be overwhelming and can delay the review process. However, this emphasis on brevity can sometimes clash with introducing significant new features. While some engineers might have reservations about the bias towards concise edits, the advantages are tangible. Smaller changes, ideally below 200 lines of code, are quicker to review, reducing the waiting time for feedback and increasing the overall development pace.

Approximately 35% of Google’s code changes are limited to a single file, emphasizing the drive for simplicity. This approach also ensures that usually, only one person reviews the code, making the process scalable and efficient. While more people might give feedback, only one approval, or “LGTM”, is required for any change. Keeping edits compact facilitates quicker approvals and ensures code health and quality maintenance over the long term.

Write Good Change Descriptions

The initial line of a change description is key and should present the nature of the change briefly. This line serves various purposes — it features in the code review tool, forms the subject of related emails, and appears in the history summary within tools like Google’s Code Search. Beyond this first line, the description should offer in-depth insights into the specifics of the change, moving beyond vague labels like “Bug fix”. If multiple connected alterations exist, itemize them, but ensure clarity and brevity.

Change descriptions are historical markers that help understand the codebase's evolution. Tools like Code Search further underline their significance, letting developers track the origins of every line. While descriptions provide a broad view, commenting within the code, especially in public APIs, is also crucial. Any obscurities in code should be clarified with structured coding or insightful comments. Lastly, if the review process brings forth new decisions, descriptions should be updated, or apt comments added, ensuring the code review remains a valuable resource for future reference.

Keep Reviewers to a Minimum

At Google, most code reviews are conducted by a single reviewer. This streamlined process, which trusts an individual to manage aspects like code correctness, owner acceptance, and language readability, scales effectively across a vast organization like Google. While the instinct in the industry might be to involve multiple engineers for varied insights, this approach often results in diminishing returns. The primary approval or “LGTM” holds the most weight, and successive reviews don’t necessarily add significant value. The added costs, in terms of time and resources, for multiple reviews often exceed their benefits. While there are scenarios where multiple reviews might be advantageous, each reviewer should have a distinct focus to maximize efficiency.

Automate Where Possible

Embracing automation in the code review process can enhance efficiency. While human input is necessary, automating certain repetitive or mechanical tasks can optimize the review process. Google, for instance, has integrated tools that permit authors to auto-submit and sync changes post-approval. A notable technological advancement in recent years is the automatic static analysis of code changes. Instead of expecting authors to run tests or format checks manually, Google’s current review tools automatically conduct these checks through a “presubmit” process before a change is forwarded to a reviewer. This automation detects issues in the proposed changes, prompting the author to rectify them before proceeding. Consequently, this reduces unnecessary back-and-forth and allows reviewers to concentrate on more critical aspects beyond just code formatting.

Types of Code Reviews

Understanding the different types of code reviews is pivotal in adopting the right approach for different scenarios. This section explores the various code reviews, offering readers a comprehensive view to choose the best fit for their needs. Code reviews at Google can be categorized based on their nature and intent. Each type necessitates different attention levels to distinct facets of the review process:

Greenfield Code Reviews

Greenfield code reviews deal with entirely new code and are crucial for determining the code’s future maintainability. Introducing new code at Google usually means addressing a genuine issue rather than adding another option. Before any code review, there’s an in-depth design review, ensuring that decisions match the original plan. For a code review to be effective, it should check if an API aligns with the previously agreed design and has comprehensive testing. The code should also identify its owners, be well-documented, and might require integration into the continuous integration system. This approach guarantees that new code meets Google’s standards and remains robust over time.

Behavioural Changes, Improvements, and Optimizations

The majority of changes at Google relate to tweaks in the existing codebase. This can involve adjusting API endpoints, enhancing current implementations, or optimizing for elements like performance. Like in greenfield reviews, the key questions remain: Is the change essential, and does it enhance the codebase? Often, the most beneficial changes involve deleting outdated or unnecessary code. Furthermore, any behaviour change should include updated tests for the modified API actions. Enhancements must be assessed in a Continuous Integration (CI) system to verify they don’t disrupt current test assumptions. Similarly, any optimizations should ensure the consistency of these tests and might also need to present performance benchmarks for evaluation.

Bug Fixes and Rollbacks

Bug fixes should be targeted, addressing only the specific problem without venturing into unrelated issues. This maintains a manageable review size and ensures easy regression testing or rollback if needed. Most bug fixes also necessitate updated tests to catch the original error, given that the bug emerged from inadequate testing or unmet code assumptions. A code change might inadvertently disrupt a dependency in larger codebases like Google's. Google provides a “rollback” option in such scenarios, allowing for a quick reversal of the previous change. However, even rollbacks need a code review. Ensuring changes are minimal and atomic becomes crucial, preventing complications during potential rollbacks. At Google, rollbacks can sometimes disrupt their work due to developers' swift integration of new code. Keeping changes small not only eases reviews but also minimizes the associated risks.

Refactorings and Large-Scale Changes

A significant portion of changes at Google are machine-generated. Even though tools create these, they still undergo review. Specific authorized reviewers evaluate low-risk changes. However, individual engineers may be pulled in to review these machine-made changes if there's a potential risk or need for expertise. While reviewing, the focus should be on the correctness of the change and not the tool or process generating it. Feedback should be specific to the local code and not the overarching tool or large-scale change process since that has already undergone a review process. If concerns about the tool arise, they should be directed to a specialized oversight group. Unlike human-authored changes, where related feedback may be appropriate, machine-generated changes shouldn’t have their scope broadened. This is because the person overseeing the tool might be juggling numerous changes, and added feedback can hinder their ability to manage it effectively.

Thank you for reading my post, and I hope it was useful for you. If you enjoyed the article and would like to show your support, please consider taking the following actions:

• 📚 If you found value in my articles and would like to support my work, consider buying me a book: Buy me a book
• 👏 Show your support by giving the article a clap, enhancing its visibility.
• 📖 Stay updated with my latest pieces by Follow Now.
• 🔔 Don’t miss out on my new posts. Subscribe to the newsletter.
• 🛎 For more regular updates, connect with me on LinkedIn.

Conclusion

Chapter 9 gives a deep dive into Google’s code review framework, showcasing its importance in preserving superior code quality and fostering teamwork. Google prioritizes code precision, readability, and uniformity, ensuring its vast codebase remains dependable and adaptable.

The chapter highlights the intangible perks of code reviews, focusing on knowledge transfer, affirmation, and responsibility. With a precise ownership structure, Google manages diverse code submissions without compromising quality.

Essential code review practices at Google involve maintaining a professional attitude, opting for minimal code alterations, and offering clear change summaries. The chapter further delineates code reviews into categories, guaranteeing that code modifications resonate with Google’s benchmarks and objectives.

To wrap up, the code review protocol at Google is a key element in its software development approach, aiding in designing and upholding intricate software infrastructures. Adhering to this chapter's outlined guidelines and best practices can benefit other firms in elevating their code standards and engineer collaboration.