Code reviews
3 likes•562 views
The document discusses best practices for code reviews. It notes that while code reviews have improved with better tooling and are now an established practice, they are often dysfunctional when teams focus on minor technical issues instead of things that make code harder to change like dependencies, large classes/methods, and single responsibility principle violations. The document recommends defining a review checklist, simple design rules, and emphasizing teaching good design. It also stresses the importance of empathy in reviews to avoid damaging team culture and productivity.
Code reviews
- 2. We believe that by reviewing code, the overall quality of software gets improved.
- 3. THE PAST ➤ < 10 years ago ➤ no good tooling ➤ not yet established as good practice
- 4. TODAY ➤ tooling is very good ➤ established good practice ➤ Everybody does it!
- 5. CODE REVIEWS ARE NOT A DISTRACTION FROM OUR JOB. THEY ARE OUR JOB.
- 6. CODE REVIEWS ARE OFTEN DYSFUNCTIONAL ➤ done inefficiently ➤ can even cause harm
- 7. WHAT IS WRONG? ➤ We concentrate on the wrong things. ➤ Technical part of the problem. ➤ We are not empathetic. ➤ Psychological part of the problem. ➤ The human factor involved.
- 8. WHAT IS WRONG? ➤ We concentrate on the wrong things. ➤ Technical part of the problem. ➤ We are not empathetic. ➤ Psychological part of the problem. ➤ The human factor involved.
- 9. WE CONCENTRATE ON THE WRONG THINGS Which are: ➤ Syntax and coding styles ➤ discuss once and then move to the linter & automate ➤ Things that are matter to personal taste ➤ and are not severe code smells
- 10. WE CONCENTRATE ON THE WRONG THINGS ➤ We tend to do “bikeshedding discussions” ➤ You get 50 comments on a small change but none on a large pull request. ➤ Low complexity => high amount of discussion ➤ Parkinson’s Law
- 14. BUT WHAT IS IMPORTANT?
- 15. MOST IMPORTANT: CONCENTRATE ON EVERYTHING THAT MAKES THE CODE HARD TO BE CHANGED IN THE FUTURE.
- 16. WHAT IS IMPORTANT? But what makes code hard to change? ➤ Too big things & too many things ➤ Concentrate on the size of things. ➤ Do one thing at a time = Single Responsibility Principle
- 17. WHAT IS IMPORTANT? But what makes code hard to change? ➤ Dependencies ➤ One object changes, other objects need to change too. ➤ Dependencies in tests ➤ The tests break with every change, though the overall functionality is not broken at all.
- 18. MORE ABOUT DEPENDENCIES AND SOFTWARE DESIGN “Most of these dependencies are usually unnecessary. They are a side effect of our coding style.” - Sandi Metz
- 19. WHAT PRACTICAL THINGS CAN WE DO NOW? … while we continuously improve our OOP design skills…
- 20. WHAT CAN WE DO NOW? 1. Define a code review checklist with your team. ➤ Start the discussion ➤ What is important in your special case, in your team setup, in your project?
- 21. CHECKLIST OF THE PAYMENT TEAM @BABBEL
- 22. WHAT CAN WE DO NOW? 2. Define a very simple rule set that declares hard upper boundaries for the size of things ➤ Classes <= 100 LOC, methods <= 5 LOC … ➤ Better design as a side effect without having to understand OO design.
- 23. WHAT CAN WE DO NOW? Help others to get better! 3. Teach good software design ➤ Share your knowledge. ➤ Code reviews are not always the best way to teach.
- 24. WHAT IS WRONG? ➤ We concentrate on the wrong things. ➤ Technical part to the problem. √linter, bikeshedding vs. things that matter, CR checklists & simple rules, teaching ➤ We are not empathetic. ➤ Psychological part of the problem. ➤ The human factor involved.
- 25. WHAT IS WRONG? ➤ We concentrate on the wrong things. ➤ Technical part to the problem. √linter, bikeshedding vs. things that matter, CR checklists & simple rules, teaching ➤ We are not empathetic. ➤ Psychological part of the problem. ➤ The human factor involved.
- 26. WHY IS EMPATHY IMPORTANT FOR CODE REVIEWS? ➤ We are giving feedback on something the other person cares a lot about. ➤ Giving good feedback involves a lot of empathy.
- 27. WHAT HAPPENS IF WE ARE NOT EMPATHETIC? ➤ People might not feel valued for their work. ➤ People might be intimidated. ➤ We hurt each other’s feelings. ➤ Fear and blame kills all creativity. ➤ People are afraid to ask questions and to ask for help. ➤ Long-term damage of the open communication culture ➤ CODE QUALITY WILL SUFFER ENORMOUSLY.
- 28. WHAT HAPPENS IF WE ARE NOT EMPATHETIC? In the worst case: ➤ People might quit their jobs. ➤ Recruiting and on-boarding new people is expensive.
- 29. WE ARE NOT EMPATHETIC There are two directions of empathy involved: The code author The reviewer Empathy for the reviewer Empathy for the code author
- 30. WE ARE NOT EMPATHETIC There are two directions of empathy involved: The code author The reviewer Empathy for the reviewer Empathy for the code author
- 31. AS AN EMPATHETIC CODE AUTHOR, YOU WANT… ➤ to make the reviewer’s work enjoyable. ➤ to avoid frustration for the reviewer.
- 32. AS AN EMPATHETIC CODE AUTHOR, YOU KNOW THAT… It is very important to give context. ➤ Choose a good PR title and description, add screenshots. ➤ Link to secondary material. ➤ Ask yourself: ➤ What might not be obvious for the reviewer? ➤ What did I try that didn’t work? ➤ Ask for specific feedback.
- 33. AS AN EMPATHETIC CODE AUTHOR… In general: ➤ You make small, single-purpose commits ➤ You open PRs early. Try to get feedback early. ➤ You make small PRs. ➤ Reduce handovers by reviewing the code yourself before ➤ reduces 50 % of problems found later
- 34. WE ARE NOT EMPATHETIC There are two directions of empathy involved: The code author The reviewer Empathy for the reviewer Empathy for the code author
- 35. The code author.. ➤ has put a lot of effort in the applied changes. ➤ might be very proud of what has just been achieved. ➤ cares a lot about his/her work. ➤ knows something that you don’t. ➤ You do not miss the chance to praise good work. AS AN EMPATHETIC REVIEWER, YOU ASSUME THAT…
- 37. know that written communication can be tricky: ➤ It is easy to put people on the defensive. ➤ You prefer to ask for clarification ➤ instead of correcting people. ➤ You consider talking privately to the code author ➤ instead of posting a huge list of comments. AS AN EMPATHETIC REVIEWER, YOU …
- 38. know that written communication can be tricky: ➤ You don’t use sarcasm. ➤ You are careful with humour, animated gifs, etc. ➤ You avoid hyperbole. (“always”, “never”, “endlessly”, “nothing”) AS AN EMPATHETIC REVIEWER, YOU …
- 39. TIPS & TRICKS FOR WRITTEN COMMUNICATION Examples of good communication: Use empathetical words: ➤ “us”, “our” and “we” instead of “you”, “your” and “mine” ➤ “We might also be able to improve our importer by …” Be humble: ➤ “I am not sure but … We can look it up.” ➤ “If I remember correctly…”
- 40. TIPS & TRICKS FOR WRITTEN COMMUNICATION Examples of good communication: ➤ “What do you think about…?” ➤ “It might also be possible to … Did you consider that already?” ➤ “I didn’t understand completely … can you explain a bit more why..?”
- 41. TIPS & TRICKS FOR WRITTEN COMMUNICATION Examples of bad communication: Be careful with “Why” questions, they often sound accusatory: ➤ “Why didn't you … ?” Avoid using commands: ➤ “Please, stop using …”
- 42. TIPS & TRICKS FOR WRITTEN COMMUNICATION Examples of bad communication: Don’t talk down to someone: ➤ “… seems like a poor solution for …” ➤ “I can’t really see why … The whole idea was...”
- 43. FINDING COMPROMISES ➤ Be aware that you will never agree on 100% of the changes. ➤ Accept that code is always only a bunch of tradeoffs. ➤ At some point, you have to ship. The discussion has to end. ➤ You can say: ➤ “That’s interesting. But can we keep it like this for now?” ➤ “You might be right in the future. But can we revisit later when we know more?”
- 44. THANK YOU! My twitter: @raphaelawrede Protect your code review culture and your healthy working environment!
- 46. MORE ABOUT CODE REVIEWS ➤ Book: Nonviolent Communication by Marshall B. Rosenberg ➤ https://www.amazon.de/Nonviolent-Communication-Language-Life-Guides/dp/189200528X ➤ Video: Implementing a Strong Code Review Culture ➤ https://www.youtube.com/watch?v=PJjmw9TRB7s ➤ Ruby Rogues Podcast: Code Review Culture with Derek Prior ➤ https://devchat.tv/ruby-rogues/216-rr-code-review-culture-with-derek-prior ➤ Blog post: Creating Your Code Review Checklist ➤ http://www.daedtech.com/creating-code-review-checklist/ ➤ Blog post: On Empathy & Pull Requests ➤ https://slack.engineering/on-empathy-pull-requests-979e4257d158#.wokp23ee0 My twitter: @raphaelawrede
- 47. MORE ABOUT SOFTWARE DESIGN ➤ Book: “Practical Object-Oriented Design in Ruby” by Sandi Metz ➤ Examples written in Ruby ➤ Book: “99 Bottles of Beer” by Sandi Metz. Just released! ➤ Book “Growing Object-Oriented Software, Guided by Tests” by S. Freeman, N. Pryce ➤ Examples written in Java ➤ Video: “Rules” by Sandi Metz ➤ Learn how to define hard upper boundaries for the size of things ➤ https://www.youtube.com/watch?v=npOGOmkxuio ➤ Video: “The Magic Tricks of Testing” by Sandi Metz ➤ Learn how to correctly use stubs and mocks ➤ https://www.youtube.com/watch?v=URSWYvyc42M ➤ Refactoring talks by Katrina Owen ➤ Follow Sarah Mei on Twitter. Tweets on OO design topics. ➤ Uncle Bob Martin. Clean Coder. ➤ Level up your programming skills with Exercism.io My twitter: @raphaelawrede