A tale of two teams

Several months ago at 8th color, we did setup a rule of “no story should be closed without a code review”. This has worked well for us so far.

Two weeks ago, I was at my consultancy gig, discussing about the Definition Of Done. Everyone was asked to write down on post-it every condition needed for a story to be “done”. We then shared those on a wall. I did contribute one with “has been code reviewed” on it. We were not doing it, but this looked like a good opportunity to start. Knowing that the convincing/evangelize part is always the most important, I expected some disagreements, but eventually got few, with the team enthusiastically agreeing to start systematic code reviews on the next sprint.

I thought it would be as simple to setup as at 8th color.

I thought the obstacle was human.

I was wrong.

A simple task

At 8th color, we use Git for version control, and GitHub as interface (and hosting) to it. GitHub double as our issue tracker.

Making a code review is a complicated task, but one with almost no overhead: I get a mail when  a new PullRequest is created (we do of course use feature branches). I can then assign it to me, look at the changes made in each file and comment in the code for any question or advice I could have. I can even commit update, should I want to.

Image may be NSFW.
Clik here to view.

Or not so simple

At the consultancy gig, we use SVN, and mostly Eclipse SVN integration as interface, with Jira as issue tracker.

My colleague Xavier had a story finished, and in our daily stand-up, he told the team he was waiting a review. He was kind enough to create a subtask for me to review his code. Then the problems started.

1. Identifying the files impacted

My first objective was to get a list of all the changes he made. Now, with SVN, we’re not using feature branches, and are instead all committing on the trunk. I started reviewing the history using Eclipse’s SVN integration. Luckily, Xavier had put the issue number in all his commits logs. Also, as the issue was recent, I did not had to dig too deep. This means I was able to get the list of changed files: two were updated and two others were new.

Still, this was already non straightforward and error prone: should Xavier had forgotten to annotate one commit log, I would never have found it (hell, maybe it is the case).

2. Reading the changes

With the list, I could then ask SVN (still via Eclipse) to show me the changes in the two updated files. Thanking Eclipse for contextual help, I was able to ask it to make a diff between the revision I was looking for and the previous one, thus getting only the last changes.

Image may be NSFW.
Clik here to view.

Eclipse’s diff is rather good – at least, it was always good enough for me to take a quick look or to merge changes. This was something different: what I wanted here was a view of all lines that had been added or deleted, and it was not that clear.

After some back & forth work between the standard editor and the diffed version, I was able to identify some redundancy in the new classes, along with some other minors stuff. Unto next problem.

3. Communicating feedback

Now, of course, those notes have no value at all if I don’t communicate them back to Xavier… But I have no direct way to annotate the code, so I had to get back my various comments into the Jira issue. As I wanted him to have it a bit easier than I did, I got back to Eclipse to note filenames and line numbers, so that he could jump easily in. This took some time again.

Overhead

This may seems a bit too much, but it is the exact situation I experienced last week. 35 minutes of archeo-codology (thanks Stéphan for the neologism) for maybe 10 minutes of actual review. My problem is not just with the cost: there are arguments enough to not do code review, so I need it to be as frictionless as possible. I was even lucky: the change was small, the code rather good.

Tooling matters

Why is my experience at 8th color so good and this one so bad? One word: Tooling.

Git allows us to make feature branches – which means listing the changes for a given story is a trivial task – whatever tool you are using.

GitHub has a nice UI for compare and Pull Requests that shows every line added and deleted. It also allows for conversation directly in the code. Pull Requests double as issues, so you don’t need an additional state. GitHub also notifies me when a new PullRequest is created.

I was missing everything there. No notification, so no way to know when a review is needed. No clear way to list the changes. No way to annotate them, to discuss.

How to start?

Now, not every team can switch to GitHub overnight. I wont be able to change the corporate rules at my consultancy gig either.

Still, take a look at Git: feature branches is the single one feature that had sold Git to me. Nothing else. Git is also very good at being integrated in existing VCS systems, so you may be able to manage it in your own team without requiring a company wide change.

If you cannot host on GitHub (for instance because the code need to stay inside the company walls, a typical requirement), see if you can install GitLab. It is an open source package that replicates most of GitHub features, notably Pull Requests.

Tweak your issue system to notify the team when a review is asked for. This can be done for instance with a specific state on Jira and a workflow action.

To be sure that people does not forget to put the issue in the commit log (discipline is hard), you can implement a commit check (that would reject the commit if no issue is specified). To help with that, you can also use something like Mylyn, that would allow the developer to specify in one click which issue he’s working on, and will add its reference to each commit.

If you are stuck on another VCS, get help by installing a code review tool like Crucible. Crucible allows you to search and cherry pick the commits you want to review. It make the whole “look at the changes and discuss them” much easier. Licence starts at 10$ – what are you waiting for? Another option is to look at “pre commit” tools like ReviewBoard (that can create reviews before you even commit, by submitting a patch).