LispCast

1. Help your users kick ass!

   This is the basis of everything! A library that doesn't make your users more powerful is not worth using!

   Your job as a library designer is to make the programmer kick butt. Give the programmer the tools he needs to learn how to use your library for all it's worth. Show him with examples. Name your functions so that they're easier to find. Make it easy to get started and make it easy to learn more.

   

   A good tool will make the user happy to work with it. Someone who is happy with a tool will send his friends to use it too. More users means more bug testing and more patches and more feature requests. An active library is a happy library.

2. Maximize feedback

   
   Increasing the amount of feedback your library gives to the programmer will help the user learn faster and more correctly. The worst thing you can actually do is to make the programmer totally unaware of what has happened after calling a function or performing an action.

   People want to see, hear, or feel the results of their actions. It helps them tune their own mental models of what the library can and will do for them. Feedback makes the experience much more enjoyable. Programmers can more easily enter flow. And when people are in flow, they enjoy themselves. Then they tell their friends.

   But don't forget about the other kind of user. The program that uses your library also needs to have information about the library's state. Programs using your library can be much more compact and intuitively written when they don't need to keep track of your library's state. Keeping track of the library's state is just as complex as rewriting the whole thing. The program needs feedback to know if something went wrong, and perhaps even how to fix it. Which brings us to . . .

3. Plan for errors

   Both the programmer and the user code will make mistakes. That's normal. Nothing is 100%. What your library needs to do is to let the user quickly and easily understand the state of the system. That way, the user can learn from the mistake and fix the problem.

   You can also provide complementary functions. So if you have an add function, implement a remove just in case it's not what the user wants. That opens the door to experimentation because your mistakes aren't permanent. Exploratory programming!

   Mistakes are great opportunities to learn how to use the library better. Make mistakes easily undoable and increase the feedback!.
   

4. Minimize complexity

   Give the user as few options as possible. Make it as impossible as possible to not get a working program. Even if it's not exactly what they would want in the end. You want your library to work with defaults and no options. When that's not possible, crash gracefully with a decent error message---one that explains what the user should have done.

   Your code should not require me, the programmer, to read pages and pages of documentation to understand every option before I have even decided whether I want to use the system or not. This is actually a crucial design place that most designers don't think about: when the programmer is deciding which library to use. Usually, the programmer picks the one that does something with little or no effort.

   I'm a big fan of writing very clear, mathematically modeled software. That's great for maintainability and checking the correctness. But it is unreasonable to assume that your users are going to read a few papers on the subject before diving into your Support Vector Regression library. They want it to work out of the box with the ideas they already have. It is important to support users that know what gamma and epsilon mean so they can tweak it to their liking. But what about the other guys? Why make them set parameters that they don't even understand?

5. Layered design

   
   Consider building your library as a series of layers. Your bottom layer defines the low-level operations. Your upper layers define operations in terms of the lower layers. Each layer adds functionality and abstraction.

   When a new programmer wants to use the library, point them at one of the upper layers. They'll be able to start quickly and they will appreciate the library earlier. As they become more proficient, their curiosity can lead them down the layers. And as they approach the bottom layer, they are more likely to understand the inner workings of the code---and thus more likely to contribute to your project.

6. Make it transparent

   The user should never be surprised. Functions should do what they seem like they should do. Name your functions well. Name the parameters well.

   Also, provide as much information as is needed to the user. Make programmatic access to important data easy.

   I don't know if I can stress this enough. Naming is very important. Firstly, it lets programmers learn what they need faster. Well-named functions are easier to guess and easier to understand their functionality. Secondly, fewer bugs. The user knows what to expect due to good names.

   Really, I know I can't stress this enough. Without an interface that makes sense from the very beginning, the user will be frustrated. Frustration prohibits flow state. No flow state means no love. You don't get love, and neither does your code. Name everything well.

So that's my take on what I wrote. Some of it's new, some of it's old. And there's a lot left out. If you want, you should go take a look at a more didactic view of the same stuff. Happy hacking!

PS Watch this awesome video:
How To Design A Good API and Why it Matters