Mere Code

Review Thoughts

noreply@blogger.com (jml) — Sat, 15 Nov 2008 01:54:00 +0000

So, I think I've figured out what it is I dislike about Twisted's review process: reviews aren't thorough enough.

This sounds a little weird, since it's actually really hard to get a patch into Twisted: it almost always takes me at least three round trips just to get something in. But I think the number of round-trips is actually a symptom of this lack of completeness.

In Launchpad, reviews are done as in-line replies to diffs. A reviewer is obliged to note each chunk of code that needs to be changed, along with exactly what needs to be changed. In Twisted, reviews are done as Trac comments and generally provided as bullet points. In Launchpad, a reviewer would say, "You need to change foo_bar to fooBar, because our coding standards require camel case". In Twisted, a reviewer might say "There are some naming convention issues".

This obviously varies between reviewers and even between reviews, but I think that the difference in technologies encourages differences in review style.

As a patch submitter, I find the in-line-comments-on-diff form much more helpful. It provides me with a convenient todo list, and it lets me know that the reviewer has looked through and tried to understand all of my code. It essentially turns the review into a series of mini bug reports with "observed, expected, how to reproduce" sections (where "how to reproduce" is "where to find").

I also like it as a reviewer, since it means less typing.

Papers and Talks

noreply@blogger.com (jml) — Sat, 01 Nov 2008 11:14:00 +0000

At the Launchpad Epic, I presented a paper on Twisted for the other Launchpadders. I think that the paper itself is a good introduction to how Twisted works and why, and I'll be publishing it here once I get a chance to format it for the web.

I did two lightning talks that might be interesting to readers. One was on testresources and the other was on how to hack like an Evil Overlord. I think I'll try present the second one at OSDC.

Lange's Law

noreply@blogger.com (jml) — Thu, 30 Oct 2008 10:40:00 +0000

"With threads, all things are possible."

Stacked branches in Launchpad

noreply@blogger.com (jml) — Thu, 16 Oct 2008 09:10:00 +0000

Via the medium of the charming Matthew Revell, I've posted about stacked branches on the Launchpad News blog. I'm so glad this is finally out.

Super Happy?

noreply@blogger.com (jml) — Tue, 07 Oct 2008 01:24:00 +0000

Does Sydney have a Super Happy Dev House or Hacking Society or anything where a bunch of busy programmers can sit down together and hack?

If not, could you please organize one for me — that'd be great.

More bzr hacking

noreply@blogger.com (jml) — Mon, 06 Oct 2008 06:34:00 +0000

I've extended bzr-establish to give it a new command: hack.

'bzr hack lp:foo' will create a repository with working trees called 'foo' and fetch the lp:foo branch into that repository.
'bzr hack --repository ~/repos lp:foo' will create a repository in '~/repos/foo', a working tree area in 'foo', fetch the branch into the repo and make a light-weight checkout in the working tree area.

You can also specify a non-Launchpad branch, e.g. 'bzr hack http://example.com/some/branch/trunk foo'. This will make a repository called 'foo', put the branch in there and... well, you get the picture.

The plugin lives at lp:~jml/+junk/bzr-establish. It's buggy, not particularly well tested and rough as guts. Still, it's worth a play.

Bazaar hacking

noreply@blogger.com (jml) — Sat, 04 Oct 2008 12:54:00 +0000

I spent a little bit of time mucking around with some Bazaar plugin ideas I've had.

The first is a command that switches from "branches and trees together inside a shared repository" to "treeless repository with lightweight checkouts". I ran it against a couple of my local repositories and it works out rather nicely. If you are thinking of using cbranch and the like, you should have a look at this plugin. If you don't know why it's a good idea, well, umm, maybe one of the other people on the Planet will blog an answer.

The second adds 'bzr new' to the command list.
$ bzr new awesomer

will create a new shared repository called 'awesomer' and a new branch in that repository called 'trunk'. If you think trunk is a terrible name, you can do:
$ bzr new awesomer devel

If you are like Tim or Aaron, you'll want your repository and branches separated from your working tree:
$ bzr --repository ~/repos/foo foo devel

I'd like to figure out a nice way of letting users specify a default directory for repositories to go into, for those people who always use the split model.

The plugin with both of these commands can be found at https://code.edge.launchpad.net/~jml/+junk/bzr-establish. As the "junk" in the name indicates, it's really rough code.

If either of these features sound like good ideas to you, let me know!

testresources: some examples

noreply@blogger.com (jml) — Sat, 04 Oct 2008 05:20:00 +0000

There's been a clamor for more documentation on how to use testresources. While I'm not qualified to show you the best way to use it, I can show you the way that I would begin to use it.

The linked files are a bunch of unit tests for database code that uses Storm. Where a real test suite might use an in-memory database, this test suite uses on on-disk sqlite database to better illustrate testresources. This database needs to be removed and built again after each test to guarantee test isolation.

You'll need testresources, Storm and testtools in your Python import path to run these examples.

The first file, complex-example.py, shows how I might do this without testresources. I create a DatabaseService class that has a setUp and tearDown of its own, and a get_store() method that tests are likely to use. This might not be the best thing for databases, but is very close to what I'd do for network services in tests, where I would need to start the service, stop it and have methods to get URLs, clients and other information about the service. If you run the file, you'll see that the database is created at the start of each test, and destroyed before the test finishes. In total, it's created and destroyed three times.

The second file, complex-example-2.py, shows how to switch to using testresources. To do this I,

added a TestResource subclass called DatabaseResource that implements make() and clean() by delegating to a DatabaseService.
changed the test case to subclass ResourcedTestCase
added 'resources = [('database', DatabaseResource())] as a class variable of the test case.

Instead of using DatabaseService() in the test, I could have, and perhaps should have, declared a module level instance of DatabaseResource. In that case, the code would have looked like:


class _DatabaseResource(TestResource):
   ...
DatabaseResource = _DatabaseResource()

class TestPerson(unittest.TestPerson):
  ...
  resources = [('database', DatabaseResource)]
  ...

Running the file shows that the behaviour is the same as the first example: the database is created and destroyed in each test.

The third file, complex-example-3.py, shows how to take advantage of OptimisingTestSuite (sic). We load the test suite as usual, adsorb (sic) them into an OptimisingTestSuite and return that. We also have to explicity declare when a test dirties the DatabaseResource. I chose to do this by adding a dirtied() method to the DatabaseService. If I had used a singleton (as above), then I would have just called dirtied on that.

Anyway, if you run the third example, you'll see that the database is created and destroyed outside the tests and that its only done twice. The test suite has been optimized by sharing resources between tests when possible.

I hope this helps explain how to use testresources. Certainly writing has been a useful exercise for me, it's highlighted that:

a list of 2-tuples isn't quite right for declaring which resources a test uses.
the dirtied API is inconvenient
TestResource remains a confusing name for the class, as it conflates the resource acquisition and cleanup with the actual resource.
Some of the API docs are wrong (notably the ones for ResourcedTestCase).
The pattern of "resource object with setUp, tearDown, dirtied (and addCleanup)" should perhaps be turned into Python code.

I long for your thoughts.

Examples:

complex-example.py
complex-example-2.py
complex-example-3.py

pyunit3k renamed to testtools

noreply@blogger.com (jml) — Sat, 04 Oct 2008 03:59:00 +0000

After thinking and talking about it for ages, I've renamed 'pyunit3k' to 'testtools'. You can now find it at https://launchpad.net/testtools or get your copy by running 'bzr branch lp:testtools'.

This is the only major API change I plan to do without introducing some sort of formal release process. The code as it stands is highly stable, well tested and in use on production systems. Download it, use it, send me patches.

Addendum
I forgot to mention that ITestResult has been removed, and thus the undocumented dependency on zope.interfaces. If this matters to you, please let me know.

LCA 2008 Conference Report

noreply@blogger.com (jml) — Fri, 03 Oct 2008 09:13:00 +0000

Yeah, yeah, I know it's a bit late. I found this while emptying out my Drafts folder and thought you guys might like it.

It's very much a personal, in-the-moment, opinionated account. I've only edited it for formatting.

Sunday, January 27

Arrived in Melbourne. Good. Next step, dump bags and get beer. Bump into skinny guys with puns on their T-shirts and hunted expressions. Follow them to pub. Rusty is buying free drinks for first-timers. I take two.

Go to Lygon Street. Eat pizza.

Monday, January 28

Public holiday today. No coffee for sale on campus. The buzz so far is that everyone loves Ubuntu, or at least takes it for granted — which can sometimes pass for love.

The chatter about Bazaar is more interesting. Everyone says "Bee-Zed-Ahh" and lists it along with Git and Mercurial. When I talk to people, they don't seem to really care about VCS, they just fall in whatever their project uses. Those who have used DVCS talk about "modern version control" (distributed) and "legacy version control" (CVS, SVN). Those who haven't aren't even aware of how much DVCS can help:

jml: [[ something about branches ]]
other_guy: yeah, I know what branches are.
jml: but we make a new branch for every single bug fix.
other_guy: what? how can you do that? isn't that an pain in the arse?
* jml takes other_guy aside and quietly explains.

The guy who talked about securing code — making sure the stuff you release is the stuff you wrote — knew about Bazaar's GPG revision signing, but didn't like it. I reckon there's some nice stuff we could do here.

At the Debian miniconf, I sat down and listened to someone explain how to use Git to make Debian packages. The speaker kept saying "... because Git is stupid" and then showed us a diagram that had more lines than a telephone exchange.

He also did an interactive demo. Before then, I hadn't seen git being used. It's not a friendly application. I mentioned this to some people on the way out and got answers that were too complex for a hallway. Bazaar rocks, we just need to get people to use it.

Went to the OpenSSH talk. It was packed, and the content was interesting, strong and a little dry. Got some ideas for improving Conch (the SSH server that Launchpad uses for codehosting).

Tuesday, January 29

At the Gnome mini conf, trying to get a leg up into contributing. My grand aim is to get a calendar on my desktop that is as beautiful and pleasurable as iCal.

It seems that lots of others share my desire. I ended up chatting to Rob Bradford from Opened Hand and a couple of other Gnome guys — it sounds like it might be approaching possible.

Found my phone charger.

Wednesday, January 30

Bruce Schneier keynoted. The talk had a few ideas but was light on point. The tutorial on hardening Linux apps was cancelled, and I'm now sitting here while Russell Coker talks about SELinux.

Thursday, January 31

Tired and cranky. Decide to do some hacking.

Friday, February 1

It's 6:45pm now and all I can think about is signing off and zoning out. Lots of cool talks today.

During the Speaker's Panel, someone asked "What was your favourite thing that happened in Open Source last year?". One person put up their hand and said "git".

testresources overhaul

noreply@blogger.com (jml) — Thu, 02 Oct 2008 12:20:00 +0000

Rob has landed my overhaul of testresources. testresources is now a lot cleaner, with more tests, more documentation and fewer classmethods. If you've looked at it before and found it a bit confusing, now is a great time to have a fresh look.

The NEWS file, README or TODO are all great places to start. Or, you could just download the branch from Launchpad. 'bzr branch lp:testresources' should do the trick.

There's still so much I want to do, but this has been the big step: getting a firm conceptual base to work from.

Flow, Interruptions and Gold-Titanium Alloys

noreply@blogger.com (jml) — Mon, 18 Aug 2008 03:21:00 +0000

As I mentioned earlier, I've just had a very productive and fun weekend of hacking on testresources. But why was it so good?

Fast Commits

Because I was working offline using Bazaar, I could make commits to testresources and they'd be done before I could Alt-Tab back to Emacs.

Fast Tests

It takes about 0.15 seconds to run the test suite. This meant I was running it all the time, which in turn meant that I was totally certain about whether the code worked all the time.

Clarity of Purpose

I knew where I was and where I wanted to go.

No Rabbit Holes

The testresources code base is small enough that it is nearly impossible to get distracted by other systemic defects. If there is such a defect, it's probably the one that you're working on right now. This might be another way of saying...

No Blockers

I wasn't waiting on anyone to do anything. There weren't any other bugs that needed to get fixed before I could continue.

No Integration

The system is about as self-contained as it gets. No signals, subprocesses or sockets: just Python. The only dependency is pyunit3k, which is small, robust, well-tested and also pretty darn self-contained.

No Interruptions

I wasn't answering questions on IRC, taking Skype calls, handling incoming email, doing the washing, checking Facebook, catching up on my blogs, watching a film or wrestling a bear. "Fast Commits" and "Fast Tests" probably fall into this category too.

In other words:

There is nothing except this. There's no art opening, no charity, nothing to sign. There's the next mission, and nothing else.

testresources: fresh blood

noreply@blogger.com (jml) — Mon, 18 Aug 2008 01:11:00 +0000

Last weekend I spent a bunch of timing hacking on testresources with Rob over at Chris's place. testresources is an extension to unittest that allows tests to specify the resources they use declaratively, so that these resources can be cleanly shared between tests. On Saturday, we talked a bit about direction and decided on some goals. On Sunday, I got busy.

The idea isn't particularly new: zope.testing has had "layers" for a long time. The key differences between testresources and Zope layers are:

You can use more than one TestResource. You can only use one layer. Allowing tests to specify many resources makes it easier to use only the resources that you need, which in turn makes for a faster test suite.
A test that uses testresources can be used independently of other testresources machinery. With layers, you pretty much need the whole shebang. This means that you can use testresources with trial, bzr, nose, tribunal or unittest.TextTestRunner.
Layers have magical inheritance stuff. testresources has no magic.
Layers do some work in subprocesses to accommodate some setUps that can have no tearDown. testresources doesn't know what a process is.

That said, I'm mainly familiar with layers from Zope 3.2—they may have changed since then.

testresources itself is somewhat old. Rob hacked up the first version about three years ago and little has happened to it since. I've always agreed with the approach, but have also had a few qualms about implementation details that made me reluctant to use it or to recommend it. Now, it's well on its way to being something that I can trust and perhaps, love.

If you are interested, check out my branch or at least flick through the TODO file.

Cool Launchpad/Bazaar hack

noreply@blogger.com (jml) — Fri, 25 Jul 2008 05:38:00 +0000

If you push a lot of Bazaar branches to Launchpad, you might want to add something like this to your .bazaar/locations.conf:

[/home/jml/Code]
public_branch = lp:~jml
public_branch:policy = appendpath
push_location = lp:~jml
push_location:policy = appendpath

Once it's there, 'bzr push' will Just Work... as long as you want it to do something like:

jml@rhino:~$ cd ~/Code/pyunit3k/trunk
jml@rhino:~/Code/pyunit3k/trunk$ bzr push
Using saved location: lp:~jml/pyunit3k/trunk
No new revisions to push.

So if I've got a branch in ~/Code/<project-name>/<branch-name>, it'll be published at https://launchpad.net/~jml/<project-name>/<branch-name>. This is only a default, of course: you can override it for a given branch by doing:

bzr push --remember <new_location>

Or you can override it for a bunch of branches by hacking locations.conf.

Neat huh?

I Love Data

noreply@blogger.com (jml) — Mon, 07 Jul 2008 07:00:00 +0000

At work, we recently started to graph the time it takes to access a branch in Launchpad via SSH, both on our staging and production servers.

I love this so much. Having this data is liberating. It's like turning on a light in a dark room: suddenly I can go from uncertain, careful, hesitant steps to bold, confident strides.

In fact, the metaphor stretches further. This new light has revealed objects of interest (that is, spikes in the time taken) that I wasn't aware of before. I need to know how long these spikes last, how they correlate with load on the system and so forth. Soon there'll be more graphs, and I'll be able to correlate them and analyze them and suck on their delicious, numerical marrow (the light metaphor long abandoned).

Regardless of whether it's liberating illumination or nourishing, savoury meat, this new graph makes me wonder why I don't chart other things I care about. Having such graphs would help me see the impact of my actions. I could chart things like my bank balance, my waistline or the number of Latin words I learned this week. Then I could answer questions like "do I spend more on Tuesdays?" or "can I afford this iPod/cake/gerund?". This is important, because when I am tempted with a sleek/delicious/perplexing iPod/cake/gerund, I fall back on my own judgment. I think it's time to confess, dear reader, that my own judgment isn't very good. And yet I continue to trust it.

The reason I don't have such graphs is that they are inconvenient to maintain. A graph of branch access times is easy. All you need to do is describe how to get the measurement, and then do a bit of once-off set up. If you want to graph your body weight, you need to get on the scales at a fixed time and then look at the dial and adjust for parallax and then write a number down somewhere and maybe note down whether this is before or after a meal and then take the number and then add it to a spreadsheet. Most online banking sites I've seen are even less convenient than this.

Getting data on life is hard, but for programming it's easy. What things do you care about on your project? Features, user experience, how fast bugs get fixed? Can you quantify these things? Can you make a pretty picture out of it? If so, do it now! Post your answers here, set up something like Cricket and then profit!

P.S. I can't believe I got to the end of this post without saying how awesome the Canonical sysadmins are. Let me correct that now. The Canonical sysadmins are heck of awesome. They could simply walk into Mortor.

Somebody Do This Please

noreply@blogger.com (jml) — Thu, 03 Jul 2008 06:17:00 +0000

<jml> What's the difference between Gobby and a wiki?
<mwh> NAT

GMail feature request

noreply@blogger.com (jml) — Mon, 30 Jun 2008 23:09:00 +0000

First, where should I make these requests?

Second, I'd like to be able to open my GMail without seeing all the new mail in my inbox. Very often, I open up GMail just to look up some fact that I've forgotten, or to put a date to a particular event. Seeing new mail and an unempty inbox distracts me, leading me down a rabbit hole of processing.

I guess a GreaseMonkey hack wouldn't be too hard.

2008

noreply@blogger.com (jml) — Mon, 23 Jun 2008 10:12:00 +0000

Firefox 3 is awesome!

Really Satisfying

noreply@blogger.com (jml) — Fri, 13 Jun 2008 05:23:00 +0000

I have just returned from the shops with a Snickers bar. The packet says that one out of every six Snickers bars will instantly win me a free Snickers bar.

So, statistically speaking, how many Snickers bars do I have? Show working.

Aren't code reviews great?

noreply@blogger.com (jml) — Fri, 13 Jun 2008 04:37:00 +0000

Ben Sussman-Collins writes about programmer insecurity and how a lot of programmers dread having others see their code.

Some of the best programmers I've worked with are in love with code reviews, and all great writers have editors. (The "linked list" is in no way exhaustive.) Personally, I see reviews as being a great opportunity to learn.

Sussman-Collins also writes about how distributed version control can exacerbate the "isolated genius" problem by shielding ones code from the public eye. This is definitely a big potential drawback of DVCS, but one that's largely mitigated by a culture of short-lived branches and an easy-to-use public registry of all branches for a project.

Another Bazaar story

noreply@blogger.com (jml) — Fri, 13 Jun 2008 01:29:00 +0000

I'm currently hacking away on Launchpad's support for "stacked branches", something that will really make Launchpad's codehosting a joy to use.

At the moment, I'm writing some tests that require a user to login. This was becoming a bit cumbersome, until I remembered something: Tim has recently landed some code to make this easy. But how do I get these changes without messing up all of the work I'm doing now? bzr shelve to the rescue!

'shelve' interactively goes through each change you've made to your current working tree and allows you to decide whether to keep a change or shelve it. It comes with a twin command 'unshelve', which lets you interactively restore your changes.

In this case, I don't even care about the interactivity, so here's what I did:


# Shelve my changes
bzr shelve --all
# Fetch the latest trunk
cd ../trunk
bzr pull
# Merge it into my branch
cd ../stacking
bzr merge ../trunk
bzr ci -m "Merge in changes from trunk to get login testing improvements."
# Restore my changes
bzr unshelve --all

The 'shelve' command comes with the bzrtools plugin, and I am basically in love with it.

As a parting shot, I should mention that things like bzrtools aren't accidents. They are natural and inevitable when you have good APIs in a high-level language and a very nice plugin system.

And now I'm off to keep working on this branch.

Real Life

noreply@blogger.com (jml) — Thu, 05 Jun 2008 01:17:00 +0000

Inspired by Mikey, I've set up my own real-life blog.

I've done this one using Blogger's "upload to remote server" feature. It looks nice, has the features I need and means less WordPress & PHP. I'm hoping to migrate this sucker to the same technology.

Neat Bazaar feature

noreply@blogger.com (jml) — Mon, 02 Jun 2008 03:28:00 +0000

Ever find yourself working away on a branch, enjoying yourself and getting just a little carried away? Maybe you're working on a feature and you notice and fix a bug that's not strictly related to that feature.

If you catch yourself in time, there's a nice little feature in Bazaar that can help with this: bzr merge --uncommitted. It will merge in the changes that you've made to your working tree but haven't committed yet.

e.g.


$ cd some-feature-branch

... hack hack hack ... oops!

$ cd ..

$ bzr branch trunk bug-fix-2357

$ cd bug-fix-2357

$ bzr merge --uncommitted ../some-feature-branch

$ bzr ci -m "Fix up bug 2357. Found this while working on some-feature."

$ bzr send

Don't know what bzr send does? Trust me, you want to find out.

What I meant

noreply@blogger.com (jml) — Mon, 21 Apr 2008 01:39:00 +0000

z3p recently blogged about a comment I made in a code review. In the review, I linked to:

That's a negative and grumpy way of phrasing an idea that I've come to value a lot: good code expresses its intent clearly.

When looking at a patch, the reviewer needs to understand two things: the intent of the code and the intent of each change to the code. To be clear on the former, you need:

intent-revealing names.

good abstractions / interfaces.

good, small tests.

simple implementations where possible.[1]

docstrings where appropriate

comments where appropriate.

That's not exhaustive, but it's in a rough order.

To be clear on the intent of your change to code, you need:

Small patches.

A good bug / spec with a good, short summary.

A review request letter, summarizing your implementation strategy, any compromises you made, gaps in testing, future work etc.

That's not exhaustive either. In #2037, I didn't understand the motivation for lots of the code, nor for some of the changes to the code.

I'm indebted to Andrew Bennetts for teaching me that the first duty of a reviewer is to ensure that the code is clear and to Tom Berger for reminding me that compromises are worth noting.

----

[1] Actually, this reminds me of something I heard a preacher say, "before I give a sermon, I go through it, find everything clever, and take it out" (I paraphrase, not having a reference on hand).

In as much as sermons and code should both be ego-free communications of ideas, I think this is sound advice for hackers.

bzr-removable

noreply@blogger.com (jml) — Mon, 21 Apr 2008 01:04:00 +0000

The plugin I talked about in a previous post is now at https://launchpad.net/bzr-removable. Please file bugs.

Thanks to Michael Hudson and Daniel Watkins for submitting patches.

You can get the plugin by typing 'bzr branch lp:bzr-removable' on the command line.