I listed all the advice I give about Pull Requests and Code Review into a short (37 pages) and free guide, with real-life examples and actionable insights.
I read this yesterday and thought it was a nice document. I saw the post still high on HN today... and zero comments. You're getting upvotes, so clearly people like it! There is a theory that the best way to generate discussion is to be subtly wrong, and so possibly this means that every reader agreed with what you said.<p>First: kudos on writing this down and sharing it under a permissive license. It's great to contribute like that, and it takes effort to produce something and generosity to license it as CC.<p>Feedback: not much, I liked it. But I want to be as useful as possible so here are my thoughts.<p>Reading, I was surprised to jump straight in to "Create your PR before the code is ready for review", because somehow I expected more of a soft landing. But I realised: it's a guide for those who know PRs and know why to use PRs, so why not jump in? Still, the intro could contain a final sentence like: "This is not a guide to encourage you to use pull requests. It assumes you already use them and know their usage thoroughly. It is a guide of practical advice how best to use pull requests and achieve the best from code review. Let's jump right in."<p>Also, on code review, one technique I find useful which I didn't see is asking questions. You did suggest to ask for clarifications, but I think this is subtly different. Sometimes, you review code you don't know: it's ok to admit ignorance and say, "I'm unfamiliar with this library, but the method name implies... are you sure that...?" Or, you can see someone made a decision, and it can be perfectly fine, but it can be useful to ask about it in order to get it documented.<p>A good code review is also a form of documentation, and can be referred back to later.