The document discusses best practices for code review from three perspectives: communication, psychology, and work processes. It provides tips for effective communication in code reviews such as using clear and concise language, sharing context, and resolving discussions properly. On the psychology side, it notes the difficulty of admitting mistakes and not taking feedback personally due to factors like self-worth being tied to work. For work processes, it recommends habits like reviewing your own code first, focusing discussions, and approving pull requests once only minor issues remain. The overall goal is for code reviews to achieve quality assurance, knowledge sharing, and collective ownership in the most efficient and pleasant way possible.

1. Hidden sides of Code Review
Dmitrii Ivanov, iOS Engineer
@ OneApp Capabilities (NL)

2. OneApp
> 50 developers per platform

4. Goals of Code review
1. Quality assurance
2. Knowledge sharing (in both directions)
3. Giving another perspective
4. Collective code ownership
(WHAT needs to be done)

5. What is a good Code Review?
• The goals are achieved (QA, Knowledge sharing, Another
perspective, Shared ownership)
• The least possible time spent
• The process is as pleasant as possible
(HOW should it be done)

6. 3 angles
Communication
2
Psychology
3
Work processes
1

7. Communication
2
Psychology
3
Work processes
1

8. Development process
Problem
Design
Implementation

9. Development process
Problem
Design
Implementation
Code Review
Problem Validation
Design Review

10. Development process
Problem
Design
Implementation
Problem Validation
Design Review
Code Review

11. Don’t skip feedback loops
Problem
Design
Implementation
Problem Validation
Design Review
Code Review
Tip

12. Don’t skip feedback loops
Problem
Problem Validation
Design
Implementation
Design Review
Code Review
Tip

13. Don’t skip feedback loops
Problem
Problem validation
Design
Implementation
Design Review
Code Review
Tip

14. Don’t skip feedback loops
Problem
Problem validation
Design
Implementation
Design Review
Code Review
Tip

15. Make Code Review your habit
“Make the desired behaviour easier then
unwanted behaviour”
Tip

16. Make Code Review your habit
• Make the desired behaviour easier
• Code Review is an important responsibility
• Make it a daily routine
• Don't make the author ask (twice)
Tip

17. Minimise the scope
• Stay focused
• Separate different types of activities (changes, refactoring,
integration, cleanups)
• Separation helps parallelisation
• Separate Design Review from Code Review
• Use automation (linters, formatters, static analysers)
tip
Author

18. Respect the scope
• If the code is not touched, don't ask to improve it
• but "touched" code might be just moved (out of scope)
• but "untouched" code might be misaligned now: function name -
content - comment (in scope)
• Special remarks and special treatment for "out of scope" comments
tip
Reviewer

19. Review your own PR
• Respect reviewer's time
• Stupid mistakes, TODOs, debug logs, temporary commented code,
formatting, ...
• Use "fresh eyes" if possible
tip
Author

20. Author's checklist
tip
Author
Ensure proposed change is focused on one topic
􀁣
Use a short and clear Pull Request title
􀁣
Describe what has changed and why
􀁣
Add screenshots (if applicable)
􀁣
Update localised strings (if applicable)
􀁣
Implement analytics (if applicable)
􀁣
Update documentation
􀁣
Implement unit tests and/or UI tests
􀁣
Test changes against showcase app
􀁣
Consider possible security impact
􀁣
General Tests
Security

21. Reviewer's checklist
• Same as for author: automation tests, localization, logging,
analytics, style guide, security impact, error handling,
documentation, entry into the change log
• Speci
fi
c for reviewer: conformance to the design, performance,
naming, readability, code duplication, single responsibility, external
dependencies, consistency ...
tip
Reviewer

22. Start high level
High-level architecture
Interfaces between components
Components (modules, scenes, features)
Data structures
Functions
tip
Reviewer

23. Distinguish objective and subjective
• Objective points
• violation of architecture, ef
fi
ciency, maintainability, testability,
security, consistency, style guide…
• author misses some context or edge case
tip
Reviewer

24. Distinguish objective and subjective
• Subjective points
• readability
• confusion
• different approach
• Mark subjective: "imho", "suggestion", “pp"
tip
Reviewer

25. Approve when only minor/subjective
are left
• A sign for the author: generally all good; can be improved, but
already good enough to be merged
• A sign to yourself: easier review if more changes are pushed
tip
Reviewer

26. Avoid repetitive comments
tip
Reviewer
URL in names of the classes should be capitalised as it's an
acronym (here and in all the other cases like
AgreementsApplicationUrl or ChatExternalApplicationUrl)
Good 👍

27. Avoid repetitive comments
tip
Reviewer
Ca we capitalise URL here as it’s an acronym?
URL-capitalisation (same as here)
URL-capitalisation (same as here)
Also good 👍

28. Don't mix several points in one discussion
tip
Reviewer
Bad 👎

29. Keep valuable discussions in PR
Tip
Bad 👎

30. Keep valuable discussions in PR
Tip
Resolved in person. We've checked together all the cases in
Payments and everything works as before

31. Communication
2
Psychology
3
Work processes
1

32. Communication is hard...
😓 between technically-skilled introverts who mostly communicate
with computers
😓 between people of different cultures
😓 when held in writing, without all the nonverbal means of
communication like facial expressions, tone of the voice, body
language
😓 when somebody is emotionally attached to the subject

33. Communication is hard...
✅ between technically-skilled introverts who mostly communicate
with computers
✅ between people of different cultures
✅ when held in writing, without all the nonverbal means of
communication like facial expressions, tone of the voice, body
language
✅ when somebody is emotionally attached to the subject

34. Channel
Message
Feedback
Receiver
Sender
Decoding
Decoding Encoding
Encoding

35. Reviewer
Author

36. Azure
PR
Review
Reviewer
Author

37. PR
Message
Message
Reviewer
Author

38. A good message is...
• Complete
• Concise (but completeness is a priority)
• Coherent (meaning logical, well-structured)
• Clear (clear to understand: no ambiguity, nothing misleading; as prepared to
be consumed as possible)
• Considerate/courteous (good manners, showing respect)
• Concrete (speci
fi
c and to the point, about the entire message as well as about
separate words used; using evidence and examples when relevant)

39. Applicable rules of communication
• Seek an understanding, don't be defensive
• Manage your emotions, don't make it personal
• Use visuals if it helps
• Stay focused on the topic
• Base your words on facts
• Don't stretch the conversation/argument for too long. But take breaks when needed
• Speaker: elaborate as clear as possible, listener: clarify, don't assume

40. Add screenshots and schemes
VS
Tip

41. Link to authoritative resources
• Trusted sources: Apple documentation, Swift Blog/Forum, Our
style guide
• Use with attention: Highly voted comments at StakeOver
fl
ow, blog
posts
Tip

42. If the discussion stalls
• Talk in person (verbal communication)
• Take a brake
Tip

43. Resolve discussions properly
• Disagree? - explain why
• Agree? - make it clear ("done", "
fi
xed", "changed")
tip
Author

44. Comment on your own PR
tip
Author
Good 👍

45. PR
Message
Message
Reviewer
Author
Decoding
Decoding Encoding
Encoding
Context Context

46. What makes a context?

47. Context
Problem
Domain knowledge
UI
Of
fl
ine discussions
Messages in PR

48. Context
Problem
Domain knowledge
UI
Of
fl
ine discussions
Messages in PR
Programming experience
Native language
Upbringing
Manner of communication
Culture

49. Shareable context
Problem
Domain knowledge
UI
Of
fl
ine discussions
Messages in PR

50. Make a proper PR description
• The problem
• High-level solution
• Valuable details
• The most important changes
• Where to start from
• Screenshots
• Impact on other features
tip
Author

51. Share enough context in comments
tip
Reviewer
Good 👍
Bad 👎

52. Non-shareable context
Programming experience
Native language
Upbringing
Manner of communication
Culture

53. Non-shareable context
Programming experience
Native language
Upbringing
Manner of communication
Culture

54. Leading
Egalitarian Hierarchical
NL RO

55. Task-based Relationship-based
NL RO
Trusting

56. Egalitarian Hierarchical
RO
NL
Leading
Trusting
T
ask-based Relationship-based
RO
NL
Low-context High-context
RO
NL
Communicating
Evaluating
Direct negative feedback Indirect negative feedback
RO
NL
Deciding
Consensual Top-down
RO
NL
Confrontational Avoids confrontation
RO
NL
Disagreeing
Scheduling
Linear time Flexible time
RO
NL
Persuading
Principles first/specific Applications first/holistic
RO NL

57. Egalitarian Hierarchical
RO
NL BE DE
Leading
Trusting
T
ask-based Relationship-based
RO
NL DE BE
Low-context High-context
RO
NL BE
Communicating
Evaluating
Direct negative feedback Indirect negative feedback
RO
NL
Deciding
Consensual Top-down
RO
NL
Confrontational Avoids confrontation
RO BE
NL
Disagreeing
Scheduling
Linear time Flexible time
RO
NL
Persuading
Principles first/specific Applications first/holistic
RO NL
DE
DE BE
BE DE
DE
DE BE
BE DE

58. Communication
2
Psychology
3
Work processes
1

59. Admitting mistakes
• Code Review is for
fi
nding the mistakes
• People don't like own mistakes
• Tension and confrontation

60. Self-work association
• We all tie self-worth with work results
• Extreme case - “workism"
• The
fl
aws in our work are perceived as personal ones
• Makes it harder to admit mistakes

61. Emotional attachment
• We get attached to the results of our work
• Discussion in a PR: 2 parents arguing about the future for the child

62. Relevant psychological phenomena
• It's dif
fi
cult to admit mistakes
• Mistakes !=
fl
aws in skills or personality
• Stay objective when discussing the work

63. Don't be personal
tip
Reviewer
Bad 👎
Bad 👎

64. Don't be personal
tip
Reviewer
Good 👍

65. Don't be personal
tip
Reviewer
Good 👍
Bad 👎

66. Don't treat feedback personally
tip
Author
Bad 👎

67. Don't treat feedback personally
tip
Author
Still bad 👎
Good 👍

68. Extra care to the PRs of new joiners
tip
Reviewer

69. PRs are not only for critique
tip
Reviewer
Good 👍

70. Thanks for listening!
All tips and references