1. Reviewing for Non-Maintainers
George Dunlap

2. Maintainers would love to have more help
reviewing

3. …but many people don't know where to
start

4. Absolutely
perfect
Ready to be
checked in
Not so
perfect

5. Goal
Help move a patch closer to being ready to
be checked in

6. But:
“First, do no harm”

7. Not so helpful:
Giving feedback the maintainer has to
contradict

8. Not so helpful:
Beat up the new guy

9. Not so helpful:
Looking for things to criticize

10. Helpful:
Helping get the patch checked in

11. Necessary?
Architecture Interface
Effective Efficient
All Cases
Correct
Robust /
Maintainable
Coding Style Patch / Series

12. Necessary?
Architecture Interface
Effective Efficient
All Cases
Correct
Robust /
Maintainable
Coding Style Patch / Series

13. Necessary to accomplish goals?
• Is it clear what the goals are?
• Do we need to make a change, or can the goals be met with existing
functionality?

14. Necessary?
Architecture Interface
Effective Efficient
All Cases
Correct
Robust /
Maintainable
Coding Style Patch / Series

15. Architecture / Interface
• Is this the best way to solve the problem?
• Is this the right part of the code to modify?
• Is this the right level of abstraction?
• Is the interface general enough? Too general? Forward
compatible?

16. Necessary?
Architecture Interface
Effective Efficient
All Cases
Correct
Robust /
Maintainable
Coding Style Patch / Series

17. Functionality
• Does it do what it’s trying to do?
• Is it doing it in the most efficient way?
• Does it handle all the corner / error cases correctly?

18. Necessary?
Architecture Interface
Effective Efficient
All Cases
Correct
Robust /
Maintainable
Coding Style Patch / Series

19. Maintainability / robustness
• Is the code clear? Appropriately commented?
• Does it duplicate another piece of code?
• Does the code make hidden assumptions?
• Does it introduce sections which need to be kept “in sync” with other
sections?
• Are there other “traps” someone modifying this code might fall into?

20. Style
• Comments，carriage returns, “snuggly braces”, &c
• See CODING_STYLE and tools/libxl/CODING_STYLE
• No extraneous whitespace changes

21. Patch
• Informative one-line changelog
• Full changelog
• Motivation described
• All important technical changes mentioned
• Changes since previous revision listed
• Reviewed-by’s and Acked-by’s dropped if appropriate

22. Consider three audiences
• The Reviewer(s)
• People looking for patches of interest
• The Archaeologist

23. Audience:
The Reviewer
• Is this patch necessary?
• Is this patch the right way to solve the problem?
• Is this patch correct?

24. Audience:
Someone looking for someting
• Patches to backport
• A patch that may have broken something
• Or a patch which fixes something

26. Audience:
The Archaeologist
–“Chesterton’s Fence”
“Don’t ever take a fence down until you
know why it was put up.”

27. Template for a changelog
• What does the current code do?
• Why is that a problem?
• How does this patch fix it?
• Any other changes the patch is making

28. Reviewing tips
• Code follows data: Look at the data structures first
• Three ways to look at a patch
• Look at the patch itself (emacs / vim ‘diff mode’)
• Look at the patched file
• Graphical diff (i.e., meld)

29. Communication:
Express Appreciation
• “Thanks for the patch.”
• “Thanks for doing this.”
• “Looks good, just a few comments.”
• “I think this is a good change.”

30. Communication:
Avoid inflammatory language;
stick to the facts

31. Strongly-worded dictionary entry:
"裹脚 (guo3 jiao3): foot-binding (a vile feudal practice
which crippled women both physically and spiritually)”

32. Wikipedia Entry on Foot-Binding:
"Foot-binding resulted in lifelong disabilities for most of its subjects. …
Binding usually started during the winter months since the feet were more
likely to be numb, and therefore the pain would not be as extreme. …The toes
on each foot were curled under, then pressed with great force downwards
and squeezed into the sole of the foot until the toes broke…”

33. Why you shouldn’t say code is “garbage”
• Makes the patch author angry
• They spend time and mental energy wrestling with their feelings
rather than coming up with solutions
• Doesn’t contain any information
• The facts are both more powerful and more persuasive

34. Your experience is a fact
• Example:
• “This confusing”
• “It took me a long time to figure out what was going on here”
• Example:
• “This is fragile”
• “This seems fragile to me”
• “If X happens, Y will happen.”

35. Necessary?
Architecture Interface
Effective Efficient
All Cases
Correct
Robust /
Maintainable
Coding Style Patch / Series