Download as PDF, PPTX
Uploaded byNina Zakharenko
How to successfully grow a code review culture
The document provides a comprehensive guide on fostering a successful code review culture, emphasizing the significance of code reviews in improving code quality and team collaboration. It details strategies for both reviewers and submitters, such as providing clear feedback, maintaining consistency, and promoting a no-blame culture. Additionally, the importance of using automated tools and developing a supportive onboarding process for new team members is highlighted to enhance the overall code review experience.
More Related Content
Similar to How to successfully grow a code review culture
How to successfully grow a code review culture
- 1. How to successfully growa code review culture @nnja Nina Zakharenko
- 2. What will welearn today? - Part 1 Why do we code review? What are the benefits? Our Code Review Process How to Grow a Culture
- 3. What will welearn today? - Part 2 How to be a Great Reviewer How to a be a Great Submitter Using Code Review to Build a Stronger Team
- 4. Not one sizefits all! team size 2 vs 10 product type agency vs in-house defect tolerance jet engines vs mobile games
- 5.
- 6. Code Reviews Can BeFrustrating
- 7. Apparent Code Review Frustrations Addstime demand Adds process Can bring up team tensions “smart” devs think they don’t need it
- 8. How do youget people to change the way they work?
- 9. Show them theBenefits are Crystal Clear
- 10. Find Design Flaws &Bugs So they can be identified and remedied before the code is complete Case Studies on Review: ➡ bug rate by 80% productivity by 15% https://blog.codinghorror.com/code-reviews-just-do-it/
- 11. The goal isto find bugs before your customers do.
- 12. Shared Ownership We’re allin this together 👀 results in positive motivation Overall increase in code quality
- 13. Shared Knowledge No developeris the only expert Developers gain familiarity with different modules via review Decrease the “Bus Factor”
- 14. 🚍 Factor? concentrated specialized knowledge willone person sabotage the project if they left?
- 15. Leave a PaperTrail Code Reviews add a wealth of knowledge! Why was a particular decision made?
- 16. Find Bugs Shared Ownership SharedKnowledge Reduce Bus Factor Leave a Paper Trail Code Review Benefits?
- 17. My current organizationhas a great review culture. As a result, I’ve become a better programmer.
- 18.
- 19. Tools We use GitHubenterprise Many other tools exist GitHub added Review tools September 2016!
- 20.
- 21.
- 22.
- 23.
- 24.
- 25. Feature Branches? Feature branchesare merged into a development branch, not master. We can QA in a staging environment that mimics production When necessary, we can hotfix master
- 26.
- 27. It starts witha Commitment Make a commitment to always Review before Merge Present the Facts Don’t force it New ideas take time to root
- 28. Code Reviews needto be Universal Doesn’t matter how Senior / Junior you are Only Senior Devs reviewing == bottleneck Inequality breeds dissatisfaction Break down old barriers and status quos
- 29. Code Review isdone by your peers, not management.
- 30. Consistent Code Your codeisn’t yours, it belongs to your Company Code should fit your company’s expectations and style, not your own. Reviews should encourage consistency for code longevity
- 31. Style Guide Distinguishes personaltaste from functionality Should be agreed upon before hand Great codebases are written by a team, but look like they were written by an individual
- 32. Consistent Code isEasier to Maintain by a Team
- 33. No Blame Culture Failureis inevitable Mistakes become team, not individual responsibility Needs management support
- 34. Blameless Post Mortems Meetshortly after Incident Resolved Understand the root cause Document how it was fixed Identify how to prevent it in future
- 35. For a blamelessculture, don’t point fingers!
- 36. “ When code reviewsare part of the culture, people don’t expect their changes to be reviewed, they want their changes to be reviewed. https://www.caktusgroup.com/blog/2014/07/28/culture-code-reviews/
- 37. Make a Commitment UniversalCode Review Performed by Peers Style Guide = Consistency How to Grow Culture?
- 38. Starts with NoBlame Culture How to Grow Culture?
- 39. How should wecode review? ?
- 40. How to bea Great Reviewer
- 41. Have Empathy Why doyou think you’re so hostile in code reviews? If only I had been more popular in High School.
- 42. Be Objective “this methodis missing a docstring” instead of “you forgot to write a docstring”
- 43. Ask Questions Don’t GiveAnswers “Would it make more sense if… ?” “Did you think about… ? ”
- 44. Offer Suggestions “it mightbe easier to” “we tend to do it this way”
- 45.
- 46.
- 47. Have Clear Feedback Stronglysupport your opinions Share How & Why Link to supporting blogs, stackoverflow examples, or documentation.
- 48.
- 49. Compliment Good Work& Great Ideas
- 50. Don’t be aperfectionist
- 51. Don’t be aPerfectionist For big issues, don’t let perfect get in the way of perfectly acceptable. Prioritize what’s important to you. Usually 90% there is good enough.
- 52. It’s OK toNit-Pick Syntax Issues Spelling Errors Poor Variable Names Missing corner-cases
- 53. It’s OK toNit-Pick Save the nit-picks for last, after any pressing architecture, design, or other large scale issues have been addressed.
- 54. Avoid Burn-Out Studies showreviewer should look at 200-400 lines of code at a time for maximum impact https://smartbear.com/learn/code-review/best-practices-for-peer-code-review/
- 55. https://smartbear.com/learn/code-review/best-practices-for-peer-code-review/ Limit Reviews to200-400 lines between 60 and 90 minutes, then take a break. Avoid Burn-Out
- 56. Do Reviews in24-48 hours
- 57. Define Done Let thesubmitter know if you approve, or if they need to make changes. Use consistent language LGTM or Changes Requested Follow up when the submitter says they fixed something
- 58. Have Empathy Watch yourLanguage Have Clear Feedback Give Compliments Don’t be a Perfectionist How to be a Great Reviewer?
- 59. Avoid Burn Out Completein 24-48 hours Define Done How to be a Great Reviewer?
- 60. How to Bea Great Submitter
- 61.
- 62.
- 63. Don’t be tooclever. Readability Counts!
- 64. “ Good code islike a good joke. It needs no explanation. Russ Olsen
- 65. Stages of Review 0before submission 1 submitted 2 (optional) work in progress (30-50%) 3 almost done (90-100%) 4 review completed
- 66.
- 67. Provide Context (TheWhy) Link to the underlying ticket/issue Document why the change was needed For larger PRs, provide a changelog Point out any side-effects
- 68. YOU are the PrimaryReviewer Review your code with the same level of detail you would give giving reviews. Anticipate problem areas
- 69. The Primary Reviewer Makesure your code works, and is thoroughly tested. Don’t rely on others to catch your mistakes.
- 70. Before Submitting, Try aCheckList
- 71. ☑︎ small stuff Didyou check for reusable code or utility methods? Did I remove debugger statements? Are there clear commit messages?
- 72. ☑︎ big stuff Ismy code secure? Will it scale? Read the Checklist Manifesto
- 73.
- 74. You’re starting a conversation. Don’tget too attached to your code before the review process Anticipate comments and feedback Acknowledge you will make mistakes
- 75. step 2: (optional) work inprogress
- 76. Submit Work inProgress PRs Necessary for bigger features Open them your code is 30-50% done Don’t be afraid of showing incomplete, incremental work This is the right time to get feedback on bigger issues with the code
- 77. When Code isWork in Progress Feedback to expect: Architectural Issues Problems with Overall Design Design Pattern Suggestions
- 78.
- 79. When Code isAlmost Done Feedback to expect: Nit Picks Variable Names Documentation & Comments Small Optimizations
- 80. One Review perIssue Solved an unrelated problem? make a new PR with a separate diff If you’re solving multiple problems, break them up into multiple PRs for ease of review. You can branch off your feature branch to keep the diff small
- 81. Prevent Reviewer Burnout Remember,reviews lose value when they’re more than 500 lines of code. Keep reviews small and relevant. If submitting a big review is unavoidable, give the reviewer extra time. https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/bosu2015useful.pdf
- 82. ✔ Check Code withAutomated Tools
- 83. ✔ Linter check syntaxor style guide violations
- 84. ✔ Tests Write tests! Don’tknow code health if tests are failing Tests Identify problems immediately
- 86. ✔ Continuous Integration automated buildwith every push
- 87. ✔ Coverage % ofcode execute when running a test suite
- 88. ✔ Coverage Coverage toolscan integrate into GitHub. coverage.py coveralls.io
- 89.
- 90. Be Responsive Reply toevery comment Common Responses: Resolved Won’t Fix If you won’t fix, make sure you’ve come to a mutual understanding with the reviewer
- 91. If there werecomments, let your reviewer know when you’ve pushed changes and are ready to be re-reviewed. It’s still a Conversation
- 92. Don’t Bike-Shed bikeshed.com back &forth > 3 times? step away from the keyboard. talk instead! record the conversation in the Review
- 93. Fight for whatyou believe, but gracefully accept defeat.
- 94. Don’t take itpersonally. It’s an opportunity for growth.
- 95. Provide the Why Reviewyour own code Expect Conversation Submit in progress work How to be a Great Submitter?
- 96. How to bea Great Submitter? Use automated tools Be Responsive Accept Defeat
- 97.
- 98. Use that asan advantage when someone new joins!
- 99. On your firstday…
- 100. Newbies Not everyone hasexperience being reviewed. Remember what it felt like when you introduced the process. Ease into it!
- 101. On-boarding Start by readingrecently completed reviews. The first submitted review is always the hardest First review should be small. Share the style guide
- 102. Everyone’s a Reviewer Juniordevs start by doing pair-reviews with a more experienced teammate. Use it as a mentorship opportunity. “When your team succeeds, you succeed.”
- 103. “ Hiring senior engineersis hard. You can hire junior engineers, and grow them into functional productive parts of your team. Sasha Laundy http://blog.sashalaundy.com/talks/asking-helping/
- 104. If you’re notdoing code reviews, you’re missing a big opportunity.
- 105. Remember… Allocate the time Develop,don’t force the culture Not one size fits all Or a one stop fix Use in addition to tests, QA, etc for maximum impact
- 106. What did welearn? ?
- 107. reviews decrease WTFs/m theonly valid measurement of code quality
- 108. less WTFs ➡ happierdevs!
- 109. bonus reading &resources at the end of the slides bit.ly/reviewcode Bonus Material!
- 110.
- 111. Resources & AdditionalReading Microsoft Study on Effective Code Review https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/ bosu2015useful.pdf Code Reviews: Just do it https://blog.codinghorror.com/code-reviews-just-do-it/ Code Project - Code Review Guidelines http://www.codeproject.com/Articles/524235/Codeplusreviewplusguidelines%20and Great Example Checklist http://insights.dice.com/2012/10/31/whats-on-my-code-review-checklist/ Best Practices for Code Review https://smartbear.com/learn/code-review/best-practices-for-peer-code-review/
- 112. Resources & AdditionalReading Rebecca's Rules for Constructive Code Review https://storify.com/ReBeccaOrg/rebecca-s-rules-for-constructive-code-reviews My Big Fat Scary Pull Request https://medium.com/@jdan/my-big-fat-scary-pull-request-2c8ac394540e#.yhs96vbxu Hacker School Environment & Social Rules https://www.recurse.com/manual#sec-environment
- 113. Example Style Guides Python https://www.python.org/dev/peps/pep-0008/ Scala https://github.com/paypal/scala-style-guide Javascript https://github.com/airbnb/javascript Googlehas many good, but strict style guides https://github.com/google/styleguide Doesn't matter which one you use. Pick one and stick with it.
- 114. Credits Special thanks toall the people who made and released these awesome resources for free: Presentation template by SlidesCarnival
Editor's Notes
- #2 Hi everyone! My name is Nina Z- I’m a developer at braintree, and I’m particularly passionate about code quality and developer productivity - You’re going to walk out of this room today knowing how to successfully grow a code review culture - Before I start, I know there are designers in this room. - Please know that I am not one of you. If my slides make you cry, please don’t throw tomatoes at me until the end.
- #3 - Firstly, Who’s the target audience? both team leaders and developers. Today, I’ll talk about: [*] why we review [*] what the benefits are [*] i’ll tell you more about my process [*] and we’ll learn how to grow and nurture a review culture
- #4 next, I’ll give specific examples of how to be an effective reviewer, [*] and an effective submitter [*] lastly, I’ll share how to use these tools to build a stronger team
- #5 This talk is not one size fits all - I’m offering suggestions - You need to Adjust them to your work situation. What are Factors?: [*] [1] team size - taking the time to review will affect a team of 2 much greater than a team of 10 [*][2] product type - if you’re an agency, you might have tighter deadlines, more incentive to try to just push code out the door. [*] [3] What is defect tolerance? The rate of failure that’s acceptable in your software [3] if you’re dealing w: money? medical equipment? you should have a lower defect tolerance than a web app or a game
- #6 - First, we should answer the question - why should we bother with code review?
- #7 - On the surface, the code review process can appear really frustrating. - Just Look at this developer. - She is so angry at the idea of reviewing code that she’s eating her laptop!
- #8 What are some apparent code review frustrations[*] [1] adds a time demand. this is especially noticeable on a smaller team [*] [2] it adds process. everyone hates process, right?[*] [3] the review process can bring up hidden tensions between team members, and can flare up egos. smart devs think they don’t need to be reviewed
- #9 - How do you get people to change the way they work? - Inspiring change is always difficult. - People get comfortable in routines. - If you don’t already code review, how should you go about introducing the concept?
- #10 Start by selling the benefits. in the short term frustrations are inevitable When you first start, expect things to be slow going. But, In the long term it’ll make your life easier. Like with all things, the more practice you have the better your velocity will be over time I’ve been on a team with reviews for over a year, it took 2+ months until it became 2nd nature for me
- #11 What’s the biggest benefit? Design Flaws & Bugs can be found and fixed before the code is done [advance] Multiple Case studies from IBM, AT&T Microsoft, have shown code review can lower bug rate by up to 80% increase productivity by up to 15%
- #12 - The goal is not to show off who’s smarter. - The goal is to save face, and find bugs in your software before your customers do.
- #13 Reviews help us feel a sense of shared ownership. It reminds us that we’re all in this together When I know someone will be looking, it motivates me to write better code This positive motivating pressure results in an increase in code quality
- #14 Reviews also help us share knowledge through the team As a developer, you can gain familiarity with different parts of the code base by doing reviews It also decreases the bus factor
- #15 what is the bus factor? [advance] measurement of how much specialized knowledge belongs to any individual team members if the bus factor is too gruesome, think of the lottery factor instead. who’s heard?“only alice works on the code for the authentication system. no one else understands how it works so they don’t want to touch it in case it breaks ” how to Measure? [advance] in your mind, go through each person in your team and ask yourself “can the project still go on if they stopped coming into the office tomorrow? think about what happens when alice wins the lottery
- #16 - Code reviews leave behind a paper trail - A review can generate a wealth of knowledge about why a particular decision was made. A good code review tool will let you review comments and dialogue that were left before a merge. That lets you go back and answer the question “Why was a particular decision made?”
- #17 What are the benefits of code review? we can find more bugs faster we share ownership in the product we share knowledge about our code we reduce the bus factor and we leave a paper trail about decisions
- #18 It’s not just anecdotes. I’ve worked as a dev for many years. I used to think I knew it all. Then I started at a company with a great review culture as a result, i’ve grown into a better programmer because there’s always an opportunity to learn from others - I started anticipating what a reviewer might point out, before even getting to the review process.
- #19 Let me give you a little more insight into our process
- #20 We use github enterprise you might hear me use the terms ‘review’ and ‘pull request’ interchangeably. [advance] But be aware that many other tools exist. [advance] I used to have reservations about Reviewing code on pull requests Lucky for us, github announced new review tools in september of 2016
- #21 - Now instead of just commenting on a pull request, you can open a Formal Review. - This lets you set a status of “approved” or “changes requested” to pull requests.
- #22 They added Threaded Inline Comments! When multiple comments were created for one line of code, it made them really hard to track. This is was of the most requested features of pull requests
- #23 administrators can now require Reviews before merging for protected branches. When Reviews are required, you must have at least one approval and no outstanding requested changes before you can merge.
- #24 make feature branch *hack hack hack* do the work open a pull request in github
- #25 1) assign a reviewer. usually ask in slack channel, someone volunteers 2) that person completes the review, says they’re done 3) when the review is complete (the reviewer says looks good to me) we merge the feature branch upstream
- #26 - What’s the benefit of feature branches? - master is always stable. development might not be. It lets us QA our changes in a staging environment that mimics production. that’s a big improvement over trying to test on our local environment. - If we need to hotfix master, we’re not affected by untested changes from the development branch.
- #27 We talked about the benefits, now let’s dive into how to grow the culture
- #28 You need to start with a commitment [*] to always review before merging code [*] Present the facts: there have been Many case studies and research papers over the past few years supporting reviews. I’ll talk about a few. [*] Suggest it, show the research,but Don’t force it. [*] New ideas take time to root.
- #29 code reviews need to be universal. [1] everyone on the team should be submitting and reviewing code. no matter junior or senior [2] if only senior dev do reviews, you’ve created a bottle neck [3] Worked with a developer in a Java shop who insisted on formatting his code C++ style instead of Java style - diff in where starting brace goes Made for nightmare diffs, and frustration among the team maintaining his code. I protest. I was told “that’s OK - he’s allowed to do that” - because Bob was the most senior engineer Many of you shaking your heads, but true story. You need to break down existing status quo for the idea to take root.
- #30 - Code review should be done by your peers, not by management. - The end goal isn’t getting someone “in trouble” Bugs found during the code review process should never come up in performance reviews That’s why we do review in the first place
- #31 Review encourages Consistent Code Need to remember an important fact: The code you write isn’t yours. It belongs to your company. [*] Code should fit company style and expectations, not your own. [*] Reviews that encourage consistency make your code more robust. [*] - Because no one stays at a company forever, code longevity is an important factor
- #32 What’s a style guide? [*] A style guide distinguishes your personal taste from functionality [*] style guides need to be agreed upon by the team before introducing code reviews. [*] Because great code bases are written by a team but, they look like they were written by an individual. I added a examples of great style guides at the end of my slides. Python has one called PEP8, it’s a built-in part of the language. Doesn’t matter which one you choose. Pick one and stick with it.
- #33 - Bob wasn’t in the wrong. Maybe C++ style formatting is in fact better. The problem was he wasn’t following convention. Consistent code will be easier to maintain by a team.
- #34 Reviews work best in a ‘No Blame Culture’ [*] Accept that failure is inevitable [*] - When the team reviews code, The team becomes responsible for code quality, not an individual. [*] Needs management support [*] if you get in trouble for sharing your mistakes, you’ll brush them under the rug next time. No blame culture should encourage teammates to openly talk about bugs found during review
- #35 As a bonus, I want to briefly touch on blameless post mortems, even though it’s a post-review process. [1] What is it? A blameless post mortem meeting happens shortly after every incident. [2] It lets you learn what the exact root cause was [3] During the meeting document the events leading up to the issue. Create a timeline. [4] Now you can learn from it, and figure out ways to prevent it from happening again. Don’t just talk about it, remember to create and assign tickets.
- #36 Who caused it is not part of the conversation This process will only work if punishment is off the table If developers think they’re going to get in trouble, they’re not going to be honest about making mistakes if you’re encouraged to share instead, everyone on the team can learn from mistakes Having a blameless post mortem is a great way for managers to show support of a no blame culture.
- #37 {Q} - How do we know when the culture has taken root? {A} - When code reviews are part of the culture, developers will are not just going to expect review. - they’re going to WANT it.
- #38 How to Grow a Culture? Make a commitment Code Reviews should be Universal They should be performed by your peers style guides encourage consistency
- #39 *It all starts with a no blame culture
- #40 - How should we code review? - There are two steps in learning how to perform reviews.
- #41 How can we be a great reviewer?
- #42 Therapist asks: - why do you think you’re so hostile in code reviews? Dev laments: - if only I had been more popular in HS code review should not look like an appointment with your therapist. Approach it objectively and without ego. Need to leave emotions behind. Have empathy - hostility is especially not necessary
- #43 Be objective. [*] this method is missing a doctoring [*] instead of [*] you forgot to write a doctoring [*] Reviews are a learning opportunity, not a chance to catch someone with their pants down.
- #44 Ask Questions, don’t give answers [*] would it make more sense if… ? [*] did you think about… ? [*]
- #45 Offer Suggestions [*] say things like it might be easier to… [*] we tend to do it this way instead… [*] It’s better to offer suggestions than to give ultimatums
- #46 Avoid these terms: [advance] Simply, Easily, Just, Obviously. They’re condescending! If it was so obvious, the submitter would not have done it in the first place. They might be missing context, or unaware of a concept. [advance] Well, actually is another one to avoid. You say it when someone says something mostly correct, but you interrupt them to make a minor correction
- #47 [anecdote] I'm not sure if any of you practice yoga, but this happens in my class all the time. The teacher will twist herself into a pretzel, and then tell the students to “now simply… [advance] - touch your feet to your forehead”. -I don’t think any of you would consider this simple!
- #48 To be effective, you need to have clear feedback [*] Your opinions need to be strongly supported to have maximum impact [*] Share how you would implement your suggestion, and why you think the change is necessary [*] Link to blogs, documentation, and other resources that back up your opinions. [*] Don’t feign surprise if someone doesn’t know something, even if you consider it a basic concept. *gasp* I can’t believe Dave doesn’t know about the singleton design pattern.
- #49 this is not clear feedback
- #50 - Remember to compliment good work and great ideas - I like to leave a thumbs up when I see: a good refactoring, some code clean up, or a particularly elegant solution Reviews shouldn’t be all about the bad
- #51 You don’t want to be a perfectionist. Rebecca said it better than I can “The goal is better code, not exactly the code you would have written”
- #52 [1] for big issues, don’t let perfect get in the way of perfectly acceptable [2] prioritize what’s important to you [3] usually 90% of the way there is good enough - When you press for complete perfectionism, you take ownership away from the person who wrote the code. It takes away their feelings of accomplishment and creativity.
- #53 Don’t be a perfectionist, but it’s OK to Nitpick the small stuff. - [1] syntax issues - [2] spelling errors - [3] bad variable names [4] missing corner-cases You might ask: - What’s the harm in letting a few of these pass by? Broken window theory - if I see sloppy code, I assume it’s OK to check in sloppy code.
- #54 Save the nit picks for last, after you’ve addressed the big stuff like architecture concerns or design decisions
- #55 As a reviewer, you want to avoid getting burned out Studies show that you should only look at 200-400 lines of code at a time for maximum impact
- #56 In practice, reviewing between 200 and 400 lines over 60 to 90 minutes will let you find 70-90% of the bugs. So, if 10 bugs existed in the code, a properly conducted review would find between 7 and 9 of them. Studies show after 500 lines, the ability to find bugs drops dramatically - If the code stops making sense, you’re too tired. You might miss something.
- #57 Good rule of thumb: Do Reviews in 24-48 hours after they’re submitted. This is especially easy when reviews are small. 500 lines of code This lets you look at reviews incrementally, prevents buildup Also means the code is fresh in the submitter’s mind for questions [advance] don’t want to end up like this guy, who’s still waiting for a code review.
- #58 For good communication, Define Done [advance] When you’re finished, say if the review is complete or if you’re waiting for the submitter to make changes [advance] Use consistent language. when you’re done you can say My personal favorite: ship it! or lgtm. If the submitter needs to push code based on your comments, say ‘Changes Requested’ - Make sure you follow up and actually the check code when the submitter says they pushed a fix.
- #59 How can you be a great reviewer? Have Empathy Watch your Language Have clear Feedback Give compliments for good work Don’t be a perfectionist
- #60 Avoid Burn out. Take Breaks But, don’t leave your teammates hanging. Finish reviews in 24-48 hours. Lastly, define done.
- #61 - We’ve spent time talking about how to be a great reviewer There’s 2 sides of the coin For effective reviews, we need to learn how to be a great submitter too.
- #62 Submitter: “no need to double check this change list, if some problems remain I’m sure the reviewer will catch them. Reviewer: “no need to look at this change list too closely, I’m sure the author knows what he’s doing.
- #63 [*** halfway point] Q: What’s rubber stamping? - When a submitted solution is so complex, the Reviewer thinks it’s obvious the author knows what they’re doing. - They just approve the code without fully understanding it.
- #64 Don’t be too clever. Submitting over complicated code is a surefire way of getting rubber-stamped. - I have a developer friend who used to love showing off how smart he was by checking in complex over engineered solutions He stopped doing it when he realized he was punishing himself. It meant that he always ended up being the maintainer of it. Remember that readability counts.
- #65 - Russ Olsen said it best. - Good code is like a good joke. It needs no explanation. - If you feel like a piece of code is confusing, it is. Leave a comment, either in code or in your review tool. Better yet, refactor it so it’s more readable
- #66 Let’s go through the stages of a Review 0: before you submit it 1: submitted 2: (this step is optional) showing work in progress. — at this stage the code is 30-50% done. 3: almost done. — here, we’re 90-100% done 4: the review is completed
- #67 Now we’re at step 0 things we need to do before we even think about starting the review
- #68 - the most important thing you can do to help the reviewer is provide context. WHY did you write this code? [*] Link to the underlying ticket or bug report [*] If there’s not enough context in the ticket, provide extra context [*] For larger reviews, consider providing a change-log [*] And try to remember to point out unintended side effects [*]
- #69 - Now that you’ve provided the context, remind yourself that YOU are the primary reviewer review your own submitted code as if you were giving a review this lets you anticipate problem areas
- #70 As the primary reviewer, it’s your responsibility to make sure your code works and it’s throughly tested always QA Your own changes. Because you don’t want to rely on others to catch your mistakes
- #71 - One way you can be a better submitter is to try a checklist before you submit your code. - What makes a good check list?
- #72 check off the small stuff [*] did you look for reusable code or utility methods? did you remove all your debugger statements are your commit messages clear?
- #73 Also use the opportunity to check for the big stuff. is your code secure? is it going to scale? I highly recommend a book called the checklist manifesto. It’s a book about how having checklists helped doctors make surgery safer, and pilots deal with disaster better. Checklists can help developers too
- #74 now we’re at step 1 you submitted the review.
- #75 At this point, you’re starting a conversation [*] don’t get too attached to your code before the review even starts [*] anticipate comments and feedback. [*] lastly, acknowledge that you will make mistakes [*] Remember that the entire point of a review is to find problems, and problems will be found. Don’t be caught by surprise.
- #76 now, we’re at step 2 which is optional submit work in progress
- #77 What’s the benefit of submitting work in progress? It’s really helpful for bigger and more complicated tasks As a rule of thumb, open them when you’re 30-50% done. You can’t be afraid of showing incomplete work. This drives the perfectionists crazy. This stage is the right time go get feedback on bigger issues.
- #78 - When your code is a work in progress - [*] - what kind of feedback should you expect? [*] architectural issues [*] overall design problems [*] recommendations for design patterns to use [*] at this stage, you want to get feedback early & often.
- #79 step 3: - we’re almost done! - we can see the finish line
- #80 What kind of feedback can we expect with the code is almost done? [*] nit picks [*] variable names [*] requests for more documentation or comments [*] small optimizations [*] - As the code evolves, it becomes more firm. - No one wants to hear “change it all!” at this phase
- #81 This is the point at which you ask yourself - Did I also end up solving an unrelated problem? [*] “ Did I only solve one issue with my pull request?” if the answer is no, break up the code into multiple reviews [*] you can even branch your code off a feature branch. this will keep the diff small
- #82 - We want to keep reviews small to prevent reviewer burn-out. [*] Remember I mentioned earlier, reviewers are not as effective when they look at more than 500 lines of code [*] Keep it small and relevant [*] if a big review is unavoidable, give the reviewer some extra time. [*]
- #83 We can use automated tools and static analysis to streamline the review process
- #84 What is code linting? it’s an automated way of checking syntax or if you want to get fancy, you can set it up to check style guide violations too this is an example of a python linter Linter can integrate with your code editor. This way the reviewer doesn’t have to waste time pointing out syntax problems
- #85 Tests. [*] Write them!! [*] Tests need to be passing for someone new to be able to meaningfully contribute. Because you don’t know the status of your overall code health if they’re failing. [*] Tests help you identify problems immediately. Not going to go into too much detail. There are many great talks and resources on testing.
- #86 If I haven’t stressed the importance of tests enough, - remember no one wants to work with the scumbag programmer who commits untested code don’t let this be you!
- #87 What is Continuous Integration? - automated build with every push. run compiler run tests - this should happen a few times a day - Lots of available tools, Travis, CircleCI. - almost all of them integrate with Github pull requests
- #88 what’s coverage? its the % of code that’s executed when a test suite runs. - Remember we talked about fault tolerance If you have low fault tolerance - for example (if your code fails, will someone get stuck in an MRI machine?) coverage can be a necessary tool
- #89 coverage tools integrate into github too for python, use coverage.py there’s also a product that works with lots of different languages called coveralls here’s an example coveralls report integrated into github - Automation saves everyone time.
- #90 - Now we’re at the last step - The reviewer has finished looking at your code.
- #91 - But, we might not be done. - If the reviewer left comments, we need to be responsive. [*] Reply to each one [*] Common responses: resolved, or won’t fix [*] If you respond with won’t fix be sure you explained by [*]
- #92 - At this point, it’s still a conversation - After the first pass, let the reviewer know when your code is ready to be reviewed again.
- #93 what is bike shedding - arguing over minor, marginal issues while more serious ones are being overlooked. i.e people arguing over what color to paint the bike shed while the house is not finished. - If you're going back and forth more than 3 times, it's time to step away from the keyboard. -Use your words instead. If you're co-located, great. Stop by and have a chat. If your remote Hop on a video call. Record the result of the conversation in the PR for posterity.
- #94 - Disagree with the reviewer's comments? No radio silence. - Carefully Explain what the reviewer might have missed. - Open a friendly discussion until you understand why the reviewer left the comment. - Maybe the reviewer missed your thought process. - But, maybe you’re just wrong. [advance slide] Learn to admit defeat.
- #95 - Admitting that you don't know something is hard. - Don’t take it personally. - You are not your code. - Use it as an opportunity to grow Remember, we’re all working towards the same goal - to ship code. Be grateful, offer thanks that someone spent the time to review your code.
- #96 How do we be a great submitter? Provide the why review your own code first expect a conversation submit work in progress
- #97 use automated tools be responsive when neccessary, accept defeat
- #98 I’ve shown you how code reviews build a stronger team
- #99 You can use that as an advantage when someone new joins
- #100 It doesn’t matter how much experience you have. on your first day, you probably feel something like this…. [advance] - “I have no idea what I’m doing”
- #101 The new person joining your team might not have experience being reviewed. If you've never had someone look at your code before, it's easy to get scared. "What are they all going to think?" Remember your first review. Ease the new person into the process.
- #102 When you onboard: - Encourage the newbie to read recently completed reviews before submitting their own Remember the 1st review is the hardest. First few reviews should be small. Don't let someone stumble around in the dark on the wrong path. Share the style guide so expectations are set. * expectations are good, but don't be rigid. evaluate new ideas or best practices the employee may have brought over from a previous org.
- #103 - Everyone should be a reviewer. How does this work with junior people? [*] - A study showed that familiarity with the code was an important factor in increasing the likelihood of providing useful comments. [*] Instead of muscling out newer or inexperienced teammates, have them do pair review with a more experienced one until they are more familiar with the code base. [*] Use it as a mentorship opportunity. [*]
- #104 Sasha Laundy said it best during a talk on Giving & Getting Technical Help. She said: Hiring senior engineers is hard. Instead, you can hire junior engineers, and grow them into functional and productive parts of your team Use your culture of review and knowledge sharing as a competitive advantage to make this process faster and easier.
- #105 - Code review is prove-ably shown to improve code quality across all kinds of organizations and code bases. - If you’re not doing code reviews, you’re missing a big opportunity. - Think about what’s blocking your team from trying some of the techniques we talked about - And Figure out ways of eliminating those blockers
- #106 Remember that for a successful culture - [*] You need to allocate the time [*] Let the culture grow organically, don’t force it [*] These ideas are not one size fits all [*] And code reviews are not a one stop fix. [*] They need to be used in addition to tests, QA, and other methods for maximum impact. - If code reviews are not already in place, anticipate stumbling blocks but in no time at all you'll say a pay off in less buggy more maintainable code.
- #107 What’s the most important thing we learned about code reviews today?
- #108 - at a minimum, code reviews decrease wtFs per minute - [advance] - and, as we know, this is the only valid measurement of code quality - we all want to work with the team on the left!
- #109 when you have less WTF moments every day, you have happier developers.
- #110 - Before I leave you today, I wanted to point out that there’s bonus material at the end of my slides - slides at bit.ly review code
- #111 Please contact me on twitter, e-mail me, and grab a copy of the slides.