If this is really going to be my research project, I’ll need to get my feet a bit more wet before I design my experiment. It’s all well and good to say that I’m studying author preparation…but I need to actually get a handle on what authors tend to say when they prepare their review requests.
So how am I going to find out the kinds of things that authors write during author preparation? The MarkUs Project and the Basie Project both use ReviewBoard, so it’ll be no problem to grab some review requests from there. But that’s a lot of digging if I do it by hand.
So I won’t do it by hand. I’ll write a script.
You see, I’ve become pretty good at manipulating the ReviewBoard API. So mining the MarkUs and Basie ReviewBoard’s should be a cinch.
But I’d like to go a little further. I want more data. I want data from some projects outside of UofT.
Luckily, ReviewBoard has been kind enough to list several open source projects that are also using their software. And some of those projects have their ReviewBoard instances open to the public. So I just programmed my little script to visit those ReviewBoard instances, and return all of the review requests where the author of the request was the first person to make a review. Easy.
Besides MarkUs and Basie, I chose to visit the Asterisk, KDE, and MusicBrainz projects.
Asterisk was a crapshoot – of all of their review requests, not a single one returned a positive.
But I got a few blips on the others. Not many, but a few.
I read all of the author preparation for each blip, and broke down what I read into some generalizations.
So, now to the meat: here are some generalizations of what the authors tended to say, in no particular order. I’ve also included a few examples so you can check them out for yourselves.
“Here’s why I did this”
The author makes it explicit why a change was made in a particular way.
Examples:
“Here’s what this part does…”
The author goes into detail about what a portion of their diff actually does.
Examples:
“Can I get some advice on…”
The author isn’t entirely sure of something, and wants input from their peers.
Examples:
“Whoops, I made a mistake / inserted a bug. I’ll update the diff.”
The author has found a mistake in their code, and either indicates that they’ll update the diff in the review request, or change the code before it is committed.
“Whoops – that stuff isn’t supposed to be there. Ignore.”
The author has accidentally inserted some code into the diff that they shouldn’t have. They give their assurances that it’ll be removed before committing – reviewers are asked to ignore.
Examples:
“Before you apply this patch, you should probably…”
The author believes that the reviewers will need to do something special, or out of the ordinary, in order to apply the diff.
“…hello?”
The review request has been idle for a while without a single review. The author pings everybody for some attention.
Examples:
Anyhow, those are the general patterns that stand out. I’ll post more if I find any.
Have you seen any other common patterns in author preparation? What would you say, if you were preparing your code for someone else to review? I’d love to hear any input.
PS: If anyone is interested in getting the full list of author prepared review requests for these 4 projects, let me know, and I’ll toss up all the links.
I frequently put in “this is where I learned about this…” type comments when I’m the author of code being reviewed.
The best example of that is when I need to enhance/fix PHP code for our public web site. I’m not a PHP guru, so in situations where I need to learn a new PHP idiom in order to write new code, I include that information in the review comments.
My reasoning is that it doesn’t make sense to put that kind of thing in the comments to the code itself. But it is helpful to the reviewers if I let them know, essentially: “Hey, I had to learn something new here; here’s the link to the resource(s) that I used to figure this out.”
So, sort of a cross between your “Here’s why I did this” and “Can I get some advice on” examples.
Which actually leads to another area of potential study (as if you didn’t have enough already 😛 ): “How I learned PHP” is *not* interesting as a comment in the code – but are there particular situations where the reviewers would have preferred that the author’s comments had been put into the *code* instead of into the code review tool?