Looks Good to Me (Adrienne Braganza) (Z-Library)

📄 File Format: PDF

💾 File Size: 15.7 MB

📖 Read Online ⬇️ Download

Registered users can read the full content for free

Register as a Gaohf Library member to read the complete e-book online for free and enjoy a better reading experience.

📄 Page 1

(This page has no text content)

📄 Page 2

"Looks Good to Me" Constructive code reviews Adrienne Braganza To comment go to livebook. Manning Shelter Island For more information on this and other Manning titles go to manning.com.

📄 Page 3

copyright For online information and ordering of this and other Manning books, please visit www.manning.com. The publisher offers discounts on this book when ordered in quantity. For more information, please contact   Special Sales Department   Manning Publications Co.   20 Baldwin Road   PO Box 761   Shelter Island, NY 11964   Email: orders@manning.com ©2025 by Manning Publications Co. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in the book, and Manning

📄 Page 4

Publications was aware of a trademark claim, the designations have been printed in initial caps or all caps. Recognizing the importance of preserving what has been written, it is Manning’s policy to have the books we publish printed on acid-free paper, and we exert our best efforts to that end. Recognizing also our responsibility to conserve the resources of our planet, Manning books are printed on paper that is at least 15 percent recycled and processed without the use of elemental chlorine. The authors and publisher have made every effort to ensure that the information in this book was correct at press time. The authors and publisher do not assume and hereby disclaim any liability to any party for any loss, damage, or disruption caused by errors or omissions, whether such errors or omissions result from negligence, accident, or any other cause, or from any usage of the information herein. Manning Publications Co. 20 Baldwin Road PO Box 761 Shelter Island, NY 11964 Development editor: Rebecca Johnson Technical editor: Miroslav Popovic Review editor: Dunja Nikitović Production editor: Keri Hales Copy editor: Alisa Larson Proofreader: Jason Everett

📄 Page 5

Typesetter: Dennis Dalinnik Cover designer: Marija Tudor ISBN: 9781633438125 Printed in the United States of America

📄 Page 6

dedication This is for you . . . you . . . my Number One. Thank you, Mario.

📄 Page 7

contents foreword preface acknowledgments about this book about the author about the cover illustration Part 1 Code review foundations 1 The significance of code reviews 1.1 Who this book is for 1.2 How this book is structured 1.3 You should want code reviews 1.3.1 Better applications 1.3.2 Elevated team understanding 1.4 Convincing your team 1.5 Making code reviews better 2 Dissecting the code review 2.1 Code review systems 2.1.1 Human-led 2.1.2 Tool-facilitated 2.1.3 Hybrid

📄 Page 8

2.2 How does a code review work? 2.2.1 The modern code review workflow 2.2.2 Our code review (pull request workflow) 2.3 Elements of a great PR 2.3.1 Title: The “what” 2.3.2 Description (the “why”) 2.3.3 Labels 2.3.4 Review states 2.4 Code review participants and expectations 2.4.1 The reviewer 2.4.2 The author 2.4.3 The team 2.4.4 Those in charge 2.4.5 The organization 3 Building your team’s first code review process 3.1 Establish your goals 3.1.1 Finding bugs 3.1.2 Codebase stability and maintainability 3.1.3 Knowledge transfer and knowledge sharing 3.1.4 Mentoring 3.1.5 Recordkeeping/chronicling 3.1.6 Choosing your code review goals 3.2 Choose your tools 3.2.1 Assessing code review functions 3.2.2 Choosing a tool 3.3 Set guidelines

📄 Page 9

3.3.1 What is our workflow? 3.3.2 What is your review focus? 3.3.3 What can block a PR from being approved? 3.3.4 What’s our approval policy? 3.4 Refining the process 3.4.1 Refinement scenario walkthroughs Part 2 Elevated code review essentials 4 The Team Working Agreement 4.1 What’s a Team Working Agreement? 4.2 Setting team expectations with a Team Working Agreement 4.2.1 Scenario 1: The swift and not-so-swift reviews 4.2.2 Scenario 2: Mismatched meanings 4.2.3 Scenario 3: To approve or not to approve? 4.3 Establishing a TWA with your team 4.3.1 Do we really need a TWA? 4.4 What to consider including in your TWA 4.4.1 More implicit code review expectations 4.4.2 Reasonable response times 4.4.3 Reasonable PR sizes 4.4.4 Issue identification 4.4.5 Self-approving PRs 4.4.6 Nitpicks 4.4.7 Positive review environment 4.4.8 What happens when a policy is violated? 4.5 This TWA is the team’s document now

📄 Page 10

4.5.1 Need to make a change? 4.5.2 Final thoughts 5 The advantages of automation 5.1 Automation as an asset 5.2 Automation prerequisites 5.2.1 Team style guide 5.2.2 Capable tools 5.3 Automations before the review 5.3.1 Formatting 5.3.2 Linting 5.3.3 Static analyzers 5.3.4 Automated testing 5.4 Automations during the review 5.4.1 PR templates 5.4.2 PR validators 5.4.3 Reviewer assignments 5.4.4 PR gate checks 5.4.5 Reminders and escalations 6 Composing effective code review comments 6.1 What makes a comment effective? 6.1.1 Objectivity 6.1.2 Specificity 6.1.3 Focused outcome 6.1.4 Effective code review comment examples 6.2 Tone of voice

📄 Page 11

6.3 Code compliments Part 3 Dealing with dilemmas 7 How code reviews can suck 7.1 Code review pain points 7.1.1 The lazy code review 7.1.2 The mean code review 7.1.3 The shape-shifting code review 7.1.4 The stringent code review 7.2 So, what do we do? 8 Decreasing code review delays 8.1 “We only have a single senior developer to review our PRs” 8.2 “I don’t understand the PR” 8.3 “There are too many files to review” 8.4 “Feature is too large to review” 8.5 “There’s too much discussion back and forth” 8.6 “Code needs to be refactored (sometimes over and over)” 9 Eliminating process loopholes 9.1 How do loopholes happen? 9.2 Loopholes (and how to fix them) 9.2.1 An undefined code review process 9.2.2 Lack of time for code reviews 9.2.3 Tool (mis)configurations 9.2.4 Lack of feedback culture 9.2.5 Approval-driven metrics

📄 Page 12

9.2.6 Taking advantage of emergencies 10 The Emergency Playbook 10.1 What is an Emergency Playbook? 10.2 What goes in an Emergency Playbook? 10.2.1 Decision trees 10.2.2 Authorization process 10.2.3 Bypassing mechanisms 10.2.4 Next steps 10.3 When do we use the Emergency Playbook? Part 4 Pairing code reviews with other practices 11 Code reviews and pair programming 11.1 Do we do code reviews or pair programming? 11.1.1 Complementing code reviews with pair programming 11.1.2 Pair programming can’t replace code reviews 11.2 Integrating pair programming 11.2.1 Convincing your team to try pair programming 11.2.2 Pairing styles 11.2.3 Considerations for effective pair programming 12 Code reviews and mob programming 12.1 Do we do code reviews or mob programming? 12.1.1 Mob programming strengths 12.1.2 Complementing code reviews with mob programming 12.1.3 Mob programming can’t replace code reviews 12.2 Integrating mob programming with code reviews

📄 Page 13

12.2.1 Complementary approaches 12.2.2 Mob programming challenges 13 Code reviews and AI 13.1 Benefits of AI in code reviews 13.1.1 Expedited reviews 13.1.2 Code quality improvement 13.1.3 Review consistency 13.1.4 Review scalability for large teams and codebases 13.2 Limitations of AI in code reviews 13.2.1 Difficulty understanding context and domain knowledge 13.2.2 Capabilities are highly dependent on training data 13.2.3 Over-reliance on AI can hinder human reviewer expertise 13.3 What can an AI-powered code review do? 13.4 Integrating AI into your code reviews 13.5 The future of code reviews: Human-AI collaboration appendix A Team Working Agreement starter template appendix B Emergency Playbook starter template B.1 Name your emergency procedure: B.2 Decision trees B.3 Authorization process B.4 Bypassing mechanism (and associated tasks) B.5 Next Steps B.5.1 Documentation appendix C PR templates

📄 Page 14

appendix D List of resources D.1 List of resources by chapter D.2 List of linters by language D.3 List of static analysis tools by language index

📄 Page 15

foreword I’ve been coding for money for over 32 years this year, and coding for free for nearly 40! I’ve taught coding at two colleges and worked side by side with developers who were far, far better coders than I, at companies all over the world, like Microsoft, Nike, and Intel, among others. Early in my career, I had my code so completely eviscerated in group code reviews that it had me sobbing in my car in the parking lot. It wasn’t until I read Adrienne’s book, Looks Good to Me: Constructive Code Reviews, that I realized that no one ever formally teaches us how to review code, or how to accept the review. It’s somehow just assumed that we’ll put a bunch of passionate coders in a room, have them warmly accept “this code sucks” as feedback, and have each happily head back to their desk to make needed changes with an open heart. You may think programming is about raw competence, you against the machine, putting lightning in a bottle in a caffeine-fueled 2 a.m. coding session. It is—when you’re a one-person shop coding for yourself. But engineers nearly always work as part of a team, and even more often, we work on very large systems that can’t be held in a single human’s mind. Programming is a team sport, and humans are a messy bunch to assemble into teams. Adrienne knows this and has assembled a practical and human-first guide to constructive code reviews. It’s filled with real-world anecdotes from her storied career, and it also looks at the code review process within the larger context of the software development life cycle. What if your

📄 Page 16

team is deep into continuous integration as a culture? What if you work in pairs? What about the “vacation factor?” Should code reviews come in pairs or in mobs? Should you use extensive tooling or just eyeballs and intuition? I appreciate that each of these questions and so many more are delved into in great depth with clear examples. Reviewing code is as important as writing code, and you’ll want to put together a process that works for your team culture. With this book, you’ll work to set a Team Working Agreement, set shared expectations, and describe a comfortable environment where everyone can bring their best selves and their best code to the table. You’ll then add in automation, PR prechecks, test coverage, and more. Whether you’re just starting out or you’ve been in the game for years, this book will set you and your team up for an improved code review culture. Thank you, Adrienne, writing a book like this is a massive undertaking. Looks good to me! —Scott Hanselman, VP of Developer Community, Microsoft

📄 Page 17

preface Ah, code reviews! We need them, but we dread them. We do them, but not well. And despite the tools we have at our disposal, we still manage to mess things up. How do we deal with gigantic PRs? How do we make code reviews shorter? Why can’t we write effective code review comments? Is SSDaaRB (Single Senior Developer as a Reviewer Bottleneck) something we just have to accept? Are we doomed to debate with our colleagues over technical implementations? Will code reviews always be like this? These questions (and plenty more) are the matters that I gravitated toward in my now 12-year career. I’ve worked on teams that had no code review process at all. I’ve worked on teams that had a process, but it was barely enforced. I’ve worked on teams that had a wonderful process. And I’ve worked on teams where the process made me want to pull my hair out because it was so tedious. As I gained knowledge in those roles, both in technologies and team processes, I couldn’t help but return to those questions. Looking back, I realized a big part of whether I enjoyed working with certain teams was whether our code review process was amicable and effective. Yes, you write code when you become a professional software developer, but you spend way more time reading and making sense of it. You also spend a lot of time reading code you didn’t write! This realization made me look at code reviews in a different light. More recently, I’ve been earning pretty pennies as a developer advocate, focused on teaching developers how to do “developer things” well. I accidentally fell into this role,

📄 Page 18

but I’m glad I did; my software development background (and apparent skills in public speaking and written communication) really helps in creating technical educational content that shines. A big part of that is because I like to focus on what I believe are essentials— things that we tend to forget or assume that everyone already knows in the software development industry—and teach them in an approachable way. When Manning asked me what topic I would want to write about, given the chance to choose anything, the choice was absolutely clear: code reviews. Are there other resources on code reviews? Absolutely. Do other developers have insights that may relate better to you? Guaranteed. But one fact remained: there is no “official” or single, comprehensive resource on code reviews, not in the way I imagined. I wanted to answer the questions I previously mentioned. I wanted to focus on the code review process and the team dynamics that surround it rather than list out code smells to watch out for (that would be a huge book if I accommodated everyone). I wanted to share all the insights, experience, strategies, and tactics I’ve learned and collected throughout my career to build a better code review. And I wanted to do it in a friendly, approachable way. I wanted to be THE book on code reviews. So that’s what I did. Now that you’re reading this labor of love, I’m excited to guide you through the human side of code reviews. I want you to do better than LGTM . I want your code reviews to be great! Thanks for caring about code reviews. Enjoy the book!

📄 Page 19

acknowledgments Writing a book is no small feat. And it’s certainly not just me that does everything. So it’s only appropriate that I give my thanks to everyone who has been a part of creating this wonderful book, both directly and indirectly. I want to thank my first (my last, my everything), my husband, Mario. For the countless conversations we’ve had about code reviews, the late-night milk teas you’ve brought me, the patience you’ve shown while I disappeared into my “writing mode,” and the undying support you’ve given me throughout this entire process, thank you. Mahal na mahal kita ♥. To Rebecca Johnson, my editor at Manning: there were many *cough* rearranged deadlines, major changes to the book’s content, and questions I had on how to navigate the book- writing process, and you gracefully guided and supported me through all of it. Thank you for pushing me to be a better writer and for being an indispensable editor on this book. To Miroslav Popovic, software architect and Software Engineering Manager at Qinshift, my technical editor: your feedback was instrumental in keeping this book as approachable for a myriad of developers as possible. Your own insights and perspectives not only enhanced this book but also kept it authentic. Thank you for playing a pivotal role in the creation of this book! David Alexander, Jonah Andersson, Devlin Duldulao, Denis Kranjčec, Garrett McCullough, Glenn Reyes, and Marilag Svennevig: thank you for the marvelous contributions to the

📄 Page 20

book. Your stories, lessons, and real-life ways of working benefited the book greatly. Thanks to all my reviewers: Asif Iqbal, Ninoslav Čerkez, Charles Chan, Dave Corun, David Krief, Deborah Mesquita, Edward Lee, Emmanouil Chardalas, Frédéric Flayol, Gowtham Sadasivam, Hazem Farahat, Jakub Jabłon´ski, Jeff Patterson, Jeremy Bryan, John Kasiewicz, John Pantoja, Jon Moore, Lin Zhang, Louis Aloia, Louis Savart, Marcus Geselle, Marlin Keys, Mehmet Yilmaz, Mustafa Özçetin, Oliver Korten, Regan Russell, Scott Bartram, Sebastian Larsson, Seth MacPherson, Shyam Burkule, Srihari Sridharan, Tim Wooldridge, Xiaoyun Yang, and Ashwani Singh. I’m incredibly grateful for all of your insightful feedback and suggestions. Even though they may have resulted in late nights, tight deadlines, and the use of every spare minute I had to incorporate them, the investment was well worth it. Thank you all for helping me create a truly worthy book. Alisa Larson, I guess I’m a bit verbose, huh? Thank you so much for going through the muddled version of my book and making it much more succinct. Your excellent edits, refining rewrites, and clarifying cuts make this book even more human-readable than I could have imagined. Thank you. Manfred Steger, although we’ve never met, I owe my book’s character, charm, and comedic breaks to you. I feel incredibly lucky to have found your set of adorable Pixelchen vectors and even more thankful that you’ve generously made them free to use. Thanks to you, the readers of the book don’t have to endure the limits of my artistic ability. To Brian Sawyer, my acquisitions editor at Manning: thank you for having that first call, taking a chance on an