Give descriptive feedback 🗳️

If you’re giving feedback, be descriptive, not prescriptive. Your job is not to fix the book. Just relay what the book makes you feel. If you’re bored by something, say that. The author and the editor will fix the book.

This is a piece of advice on how to give feedback in a writing group. The advice comes from a course by fantasy writer Brandon Sanderson, as captured by Lars-Christian Simonsen.

Reading it caused me to stop and reflect on how I give feedback. Not necessarily in a fantasy writing context¹, but in general. Even more specifically, what do my pull request (PR) review comments look like?

As a quick example, a descriptive comment versus a prescriptive one could look something like this.

I found it hard to follow why foo calls bar in this context.

Add a comment to the bar call to clarify why this call is necessary in this context.

I like the idea of descriptive feedback. To just convey my experience without suggesting an action. To not be a backseat driver, trying to take over the PR through comments. I hope I don’t do that too much, but I’m afraid I’ve been guilty of it more than once.

Avoiding prescriptive feedback is an exercise in humility too. As a reviewer, it is easy to think that you’ve fully understood the problem and that your solution would be better. But is that true? It may well be that the author have already tried that solution and found that it did not work. In the above example, is adding a comment really the best way to solve the issue?

On the other hand, as the author of a PR, it is pretty nice to get easily actionable comments. So I just can fix them and get the PR merged. So in some cases prescriptive comments are helpful, perhaps even with a concrete code suggestion.

With that said, reading descriptive feedback and having to put yourself in the reviewer’s shoes may be valuable for the PR author. It is not always easy to understand how code you write will be received by others. (I would like to know if, for example, one of my colleagues find a particular piece of code I wrote unusually hard to understand.) And even if you as a reviewer do know better, letting the author figure it out can help them improve.

Going forward, I will give it a try. I will attempt to write more descriptive PR comments, and fewer prescriptive ones. It will be interesting to see how it goes.

What do you think?