One thing which I think about often is the design of code, software libraries and APIs. I've been working on deriving some principles from the things I do intuitively based on experience. Whether those are useful to anyone else is an open question. Peer review is the best tool for figuring out if these really make sense or not, so I'd appreciate feedback on my next few blogs - hopefully one day they can make up some articles or a book or similar.

Whether the results are of value is not for me to judge. If, at worst, what comes out of this is a healthy debate and identifying some things that are not good ideas, that has value too.

Why is a subject like API-usability interesting? Well, the history of software is a history of libraries. Libraries have APIs. An operating system is a set of libraries. The Apache web server is a set of libraries. The Java platform is a set of libraries. The set of things people simply take for granted when they write code are things provided by libraries. If you're writing code, you're usually creating an API whether you know it or not. Better API design skills on average means more software that people can use and rely on faster.

There are plenty of prescriptive books on coding - Effective Java is one of the best, and I recently reread it. I do hope some prescriptions can come out of this writing; what I miss in prescriptive books is the sort of “Here's how to think about such and such a problem in order to arrive at a good solution” advice that helps one to know when one has encountered the illness the prescription cures.

A good little computer scientist is very tempted to avoid anything that isn't more-or-less mathematically provable, or at least demonstrable from statistical evidence.

But objects are a convenience for human beings! There is a psychology of how you carve a problem up into objects, how you name things, and so forth. Some ways will be easier to use for the majority of people than others. Yet, at the same time, design is a matter of balancing sometimes fuzzy principles of code ease-of-use with the requirement that the result ask only a sane amount of work from the computer, and sometimes you still have to let the computer win.

Take, for example, the argument against mixing concerns in a single class. There are excellent arguments from the perspective of architectural purism, and from the perspective of code reuse, for why mixing concerns is a bad idea. What I seldom see articulated is the simple notion that if you mix concerns, people will have a harder time understanding how to use what you create. You can't write a proof for that - and there will be cases where mixing concerns actually is the optimal solution. Those are the dark waters I would like to venture into.

There is much fascinating research to be done in the area of api-usability. To be done properly, that should involve not only programmers and usability experts, but cognitive psychologists. It would be wonderful to have such research, and would also take years to do, and I suspect cognitive psychologists have their hands full with problems more interesting to them than how to design an API.

In the absence of such research, perhaps some thoughts from one humble programmer will stir up some wisdom.

The problem with writing this sort of thing is that often you cannot write about single patterns or principles in isolation - the point is how a number of patterns interact. This inevitably makes the subject complex. For example, this first of these, which I will post shortly, touches on

• Statefulness and Model Driven Architecture
• The Don't Call Us, We'll Call You principle
• The listener pattern being more harmful than good, and
• Threading models.

Hopefully your feedback, flames and/or howls of protest will help sort the relevant from the irrelevant. Don't be sparing - if I don't post at least one thing that is approaches dead-wrong, I'm not thinking hard enough.