Making an API Hard to Misuse

Rusty Russell (of Linux kernel hacking fame) has been spending some time recently thinking about what makes for a good API. His first article on the subject was APIs: "Easy to Use" vs "Hard to Misuse", where he pointed out that the subtlest requirement for a good API is that it be hard to misuse.

He's continued this theme in his latest post, How Do I Make This Hard to Misuse?, he discusses one aspect of the matter: not how to write a good API, but how to create one that's hard to misuse. Anyone who develops software for a living can tell you that "easy to use" does not necessarily mean "hard to misuse"!

Rusty puts together a "hard to misuse" scale that starts at "It's impossible to get wrong". It's interesting that, as you go down the scale, there's a transition from "hard to get wrong" to "hard to get right". The worst possible state you can be in, at least by this scale, is "Read the correct mailing list thread and you'll get it right" - in other words, an API that is so difficult to use that you can't make it work without some form of expert guidance.

As with a lot of articles of this type, the value isn't really in any one particular suggestion. If you're a software developer, you'll read through this and think, "Well... yah. Sure. I do that." You might find one or two items at the top of the list that are new to you; but that's not what caught my attention. Instead, the real value of the this article is in getting you to think about an old problem (API design) from a different point of view - something that's almost always worthwhile.

A Guide to Proper Behavior for Children of All Ages

My friend Ben Cox came up with a flowchart for children. In his own words:

"I've come up with a flowchart you might enjoy. It's a comprehensive flowchart for children to follow, outlining proper behavior in all cases. It can be used in all situations and I've think I've covered all the bases, enough to handle any scenario that they should be expected to encounter. Unfortunately I think it may be too complex for most children under the age of 8 to navigate successfully."

And, of course, the flowchart itself. While I agree with Ben's assessment - it is rather complex - I think that, overall, it presents children of all ages with a completely satisfactory methodology for determining proper behavior in all circumstances.

... and there is no new thing under the sun.

"The thing that hath been, it is that which shall be; and that which is done is that which shall be done: and there is no new thing under the sun." - Ecclesiastes 1:9

Geekalerts reports on a company that - in a fit of creativity - has managed to come up with a new-computer form factor: a keyboard with a built-in computer!

Well, OK - maybe not all that new, given that this is essentially what the Commodore 64, the TRS-80 Color Computer, the Amiga, the Atari looked like... in fact, just about every personal computer from the dawn of the PC age used this form factor, and a connection to an existing "monitor" (your TV set) for the display. So while this is a neat little machine that packs a lot of power into a small form factor, the company's claims that "the new ZPC-GX31™ is a true innovation" seems just a bit over the top.

In The Beginning was the Command Line

I read In The Beginning was the Command Line years ago, and came across a reference to it again today. I'm posting about it because if your profession is software development, this article-slash-paper-slash-book by Neal Stephenson is one of those things that's worth going back and re-rereading from time to time.

An ext3 deleted files recovery HOWTO

Found this writeup about deleted file recovery from an ext3 file system via Linux file system guru Val Henson's blog.

If you're a file systems junkie, the article is Good Stuff, as is Val's blog. There's a lot of interesting file systems work being done with Linux these days. Thanks to my current employer (NetApp), I've got a professional interest in this sort of thing now... but I'll admit that, even if I were employed elsewhere, I'd still find the writeup of the ext3 structure fascinating. That kind of stuff is like crack cocaine for computer geeks.

More Schmooze, Less Snooze

You learn something new every day, or at least you should. In my browsing today, I came across an interesting little article from David Spark over at Spark Media Solutions - More Schmooze, Less Snooze: How to Deliver "The Most Talked About" Conference Session. While the web version of the article is broken up into one or two paragraph sections you can page through like almost like a presentation, you can also grab a pdf and read it in one go.

I've attended my share of conferences and panels, over the past decade or so - both technical and non-technical. I've even helped put together a couple of panel discussions, and I am hoping to do so again sometime soon as part of my church's new adoption ministry. So when I came across the link, I honestly thought, "Heh. Bet it's a bunch of generic advice and a sales pitch for his consulting company."


This is a genuinely interesting, informative, and quick (10-minute) introduction to panel discussions from three significant points of view: that of the panelist, the moderator, and the audience member. I can't recall a single sales pitch in the text other than the expected reference to the author's company. After finishing it, my impression is that this was written, not to showcase Mr. Spark's abilities or companies, but because he honestly wanted to help people learn to do something better.

As I read his advice on how to make a great panel presentation, I found myself thinking back to those experiences. Now, I'm not the mot observant person in the world - I'm downright clueless sometimes - but even I could see the points he was making, and line them up against the panels I've attended. The clueless moderator? Check. Panelists who want to talk about themselves or their company to the exclusion of all else? Check. Panelists who just go on and on and on and... oh, yeah, check.

He gives examples of these and a host of other panel pitfalls, and goes on to give advice on how to deal with the problems if they arise. If you're like me, and you've seen panels done but never understood the how & why of what makes a good panel discussion, then this is definitely interesting reading. If you're an experienced panelist or moderator, then these probably are rules you've either discovered on your own, or come across before; but they're presented in a memorable and easily readable (and remembered) format. Whether the principles presented are new or review, this is a worthwhile way to spend a few minutes if you happen to have a panel discussion somewhere in your future.

Asking the wrong question

Shamus Young over at Twenty Sided has posted a couple of articles on the subject of PC gaming and DRM. Part 1 of "The Publishers vs. The Pirates" is interesting, but Part 2 is what really caught my attention.

(By the way, I'm under no illusions that I'm in any way, shape, or form going to contribute anything to Mr. Young's readership. This is the guy that did DM of the Rings, for crying out loud. Unlike poor schmoes like me, he thinks in terms of 64-bit hit counters. So if you happen to wander by this blog, and you've never visited Twenty Sided, you really should go check it out. He's way smarter than I am, and a much better writer as well. Go.)

Shamus' argument - which I agree with entirely - is that piracy is a social problem, not a technological problem. Because it's not a technological problem, throwing technological solutions (increasingly strict DRM) at the problem really isn't solving anything.

It really comes down to a problem of perception. The PC game publishers decide that they can increase sales if they can keep people from pirating their game, so they look for ways to stop piracy. New license key schemes, requiring a CD in the drive to play, online activation, increasingly intrusive DRM schemes... They're engaged in a technological arms race, and like anything else in the tech market, innovations come rapidly, from both sides.

The problem is, they're really asking the wrong question. They're asking how they can keep people from pirating their games; but that's not what they really want. What they really want is to increase their sales. As I've mentioned in a recent post about eBooks, giving away something can be a way to increase sales. Here, the PC games publishers don't even need to give away anything (except maybe demos). All they have to do it stop throwing money, time, and man0hours into developing, shipping, and supporting code that nobody likes and which is really doing them no good. If dropping DRM causes a 100% increase in piracy, do you really care if it also results in a 30% increase in sales?

Sooner or later - hopefully, before the PC game industry damages itself too badly with delusions of DRM - they'll come to their senses, and start asking the right question.