A point of view is not a bad thing

In the North American tradition of journalism, it is considered inappropriate for journalists to have actual opinions about the news stories they are covering. But humans have opinions, and everybody knows that, so suppressing this is a ridiculous fiction. What’s pernicious about this tradition is that journalistic writing is more compelling when authors write in their own voice, instead of the detached view from nowhere  shtick that Jay Rosen (rightly!) complains about. It’s even worse in analysis-type pieces, because the journalist is supposed to express their opinion in the piece, but aren’t allowed to do so explicitly, so what happens instead is they find sources they agree with, and then publish quotes from those sources.

This piece by Dave Weigel from a few days ago is an example of the kind of journalistic writing that becomes possible  if a journalist writes in their own voice. Great stuff, and the Washington Post is much poorer for having let him go.

When something you believe is false

When you’re programming, and the program you’re working on behaves in some way you don’t expect, then by definition there’s some assumption you’ve made about the system that’s incorrect.
Today I was working on adding some fields to a Django admin interface, and I got an unexpected error message when I tried to create a new object in the admin interface and save it. The code was very similar to other code I had previously written that already worked, so I tried to figure out what was wrong by identifying the difference.

The important difference I couldn’t see was that the name of a variable was the source of the problem. In this particular case, the field name (image) was colliding with the field name in a grandparent class, which caused the error to occur. I hadn’t considered that the name of the variable was a meaningful difference that could cause a problem, until I did a search on Stack Overflow and found someone who encountered a similar problem.

This is one of the hardest parts of programming: being able to systematically test your assumptions until you discover which of your current beliefs are false.

There is no toggle lock signal

Since I now work within walking distance of the house, our family downsized from two cars to one, with the expectation that we could use zipcar for those times when we both need a car.

Today was the first time I used the service, and I was pretty impressed with how well the workflow was thought out. A number of my questions about the service were quickly answered. (“How do you get in the car? There’s a scanner on the windshield that senses your Zipcard. Where do they put the keys so they don’t get lost? Keys are attached to a zipline mounted near the ignition. What about gas? There’s a debit gas card that lives in a special sleeve in the driver’s visor. How do they prevent gas card fraud? When you use the card, the pump requires you to input for your mileage and your zipcard number.”)

The first time I left the car, I locked it using the normal power door lock. When I tried to get back in by scanning my card, it locked the doors again instead of unlocking them. I swiped again, and I was in.

Why did scanning my card the first time lock the doors again? I don’t know for sure how the scanner mechanism is implemented, but I can take a guess. The scanner can send a “lock” or an “unlock” signal to the car, just like a regular key fob. However, it has no way to query the car for the state of the lock, so it has to keep the state of the lock’s internally. The first time I swiped my card, the scanner was in the “doors are locked” state, so it sent the unlock signal and switched to the “doors are unlocked” state. When I got out of the car and locked it with the power lock, the Zipcar scanner was still in the “doors are unlocked” state. When I came back and swiped, it thought the doors were unlocked and so it sent the “lock” signal and switched to the “doors are locked” state.

This problem could be avoided if the car could receive a “toggle lock” signal in addition to “lock” and “unlock”. In that case, the scanner wouldn’t need to keep state internally, and could always send out the “toggle lock” signal.

Alas, there is no “toggle lock” signal.

How do you capture that?

This email from the OpenStack mailing list is a good illustration of the design rationale capture problem:

To: Yun Mao <yunmao@xxxxxxxxx>
From: Vishvananda Ishaya <vishvananda@xxxxxxxxx>
Date: Thu, 1 Mar 2012 12:36:43 -0800

Yes it does. We actually tried to use a pool at diablo release and it was very broken. There was discussion about moving over to a pure-python mysql library, but it hasn’t been tried yet.

Vish

On Mar 1, 2012, at 11:45 AM, Yun Mao wrote:

> There are plenty eventlet discussion recently but I’ll stick my
> question to this thread, although it’s pretty much a separate
> question. 🙂
>
> How is MySQL access handled in eventlet? Presumably it’s external C
> library so it’s not going to be monkey patched. Does that make every
> db access call a blocking call? Thanks,
>
> Yun
>

The problem here is that a database query can block an OpenStack Compute service from running until the query completes, because the implementation uses a green threads library (eventlet) instead of native threads. The OpenStack developers implemented  a non-blocking solution, but the solution broke things, so it was abandoned.

This is really a challenge problem for software engineering: how do you capture this type of information so that a new developer can understand why the code was implemented that way, without depending on the existence of something like the OpenStack mailing list?

My hypothesis is that building up this knowledge incrementally is the best way to go, using a StackOverflow-style Q&A approach. It would be great if we could write a comprehensive design document, but I don’t think it’s possible to know in advance what sort of questions your future reader will want answered. But if you build it based on answering people’s questions, then that frees you up from trying to guess what it is they will need to know.

Here’s another study I’ve always wanted to run: evaluate how well an author of software documentation can predict:

  • what sort of questions the documentation reader will want answered by the docs
  • the amount of prior knowledge the reader will already have

Unit testing: because all of the cool kids are doing it

While it’s fun to dump on the faddishness in software development, the rise of unit testing represents real progress in the state-of-the-practice. As an example, in the Django framework where I spend most of my time, I appreciate how much the framework helps me begin writing and running unit tests.

Thanks go to the test-driven development movement for making testing cool and inspiring an ecosystem of automated unit testing tools, even if it turns out that TDD itself provides no measurable benefits (the evidence to date is mixed).