back
2 comments
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.

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.

Feedback: not much, I liked it. But I want to be as useful as possible so here are my thoughts.

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."

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.

A good code review is also a form of documentation, and can be referred back to later.

Wow thanks for this amazing and useful feedback! I’m glad you liked the book, and will take your suggestions into account :)