How to use GitHub for [CDK|Bioclipse] code review

Triggered by posts in the past three days, I though about writing up a short tutorial on how to perform code review for existing code on GitHub. Therefore, this applied to CDK and Bioclipse source code, many but will work for any project hosted in GitHub. Even if it is not, you could consider putting up a copy there yourself. This example will demonstrate the procedure on CDK functionality in Bioclipse in the bioclipse.cheminformatics repository.

Click on the images to get a higher resolution version.

Step 1: find the class you want to review
Use the GitHub web interface to browse your way towards the source code of the class you want to review. For example, the SmartsMatchingHelper.java:



Step 2: identify something you like to comment on
Next step is to perform some code reviewing. For example, we might want to ask something about how parseProperty() works:

Now, this page on GitHub does not provide the means to leave comments; instead, you comment on commits.

Step 3: find the last commit that touched the line you like to comment on
Git has a blame option (also called annotate) which will show you for each line who last changed that line. The GitHub web page makes this functionality available with the 'blame' link just above the first line of the source code:

This link will lead us to a page with a new column on the left side showing commit hashes, name of the commit author, and the first few characters of the commit message. For example, the web page bits relevant to code we want to comment on, looks like:

This shows us that commit 3ce78ba5 is the one we are interested in:



Step 4: Look up the line again and add a comment
In the web page with the appropriate commit looked in the previous step, you scroll down to the line you want to comment on. If you hover over that line, a blue comment bubble will show up on the left side:

Clicking that blue comment icon, you get a dialog where you can enter your comment:

The 'Add Line Note' button confirms and saves your comment:



Step 5: inform the commiter about your review
The next step would be to inform the commit author. GitHub actually helps here, and should send a message, like this one:

But it would certainly not hurt of you filed a bug report or sent an email.

Now, I should only convert this into a screencast...

Bioclipse and Gist integration

As you might have read, Bioclipse has scripting support (see for example, Scripting JChemPaint), and that we have been collection them on Gist and indexing them on Delicious with the tags bioclipse and gist. This provides a nice overview of what you can do with the current SVN version of Bioclipse2. And, hopefully, when released, allow users to quickly learn about Bioclipse features, allow people to share scripts etc. Think of it as MyExperiment.org for Bioclipse.

Now, what was missing until today, was easy access to gists in Bioclipse itself. No gist.load(33421) yet. There still is not, but I uploaded earlier today a Wizard for it. (The manager will follow later). Right click on an open Project, select New -> Other, and pick Download Gist:

and click Next:

Then, just type the number of the Gist you want to open in Bioclipse, for example 18315 (see Bioclipse2 Scripting #1: from SMILES to a UFF optimized structure in Jmol), and click another Next to select a file name and location:

The current code does require you to know the Gist number, so you'll need a web browser to look it up, but we do have search facilities in mind. Also, while the code attempts so, the resulting Gist is not automatically openend in an editor (a bug). Another idea is to just install the egit plugin in Bioclipse :)