Blog by Sumana Harihareswara, Changeset founder
Zulip & Good Code Review
Hi, reader. I wrote this in 2016 and it's now more than five years old. So it may be very out of date; the world, and I, have changed a lot since I wrote it! I'm keeping this up for historical archive purposes, but the me of today may 100% disagree with what I said then. I rarely edit posts after publishing them, but if I do, I usually leave a note in italics to mark the edit and the reason. If this post is particularly offensive or breaches someone's privacy, please contact me.
As Changeset Consulting I've recently done some tech writing work for the Zulip open source project (check out my pull requests for the nitty-gritty). And I've gotten to work with Tim Abbott, Zulip's maintainer, including taking his feedback and course-correction. Often, in the software industry, we pretend or assume a dichotomy between brutal clarity and kind vagueness, especially when it comes to criticizing other people's work. Getting to work with Tim has been a welcome and consistent reminder that you can be straightforward and respectful when you need to give negative feedback.
Here's an example: Tim reviewing a pull request. Check out how he starts by saying it looks good, and then offers suggestions on how to break the patch into logical commits -- and how he makes sure to explain why we want to do that (including a link to a document that explains the reasoning and customs in more detail). Tim also tells the code author that it's fine to deviate from his specific suggestions, but gives him some guardrails. Since rebasing can be tricky for people who haven't done it much, he even suggests some git commands and tools that'll make things easier, and offers to clarify if needed. And Tim wraps it up with a thank-you and a quick explanation about why he's being so rigorous in reviewing this particular patch (security considerations).
It's thoughtful, kind, clear, and collaborative. It's the seventh comment Tim's offered on this pull request, as the author's iteratively improved it, and it shows no hint of impatience. Good stuff.