Just a Thought...

Creating APIs and libraries can be a difficult task. There are many concerns that you have to worry about such as design consistency, correctness, function, performance, security, and the list goes on. Something that typically gets lost in the list of concerns is usability . I know you might be thinking I’m nuts because APIs and libraries don’t have a graphical user interface. Yet they do have a user interface. The users of APIs and libraries are developers, and they use the exposed functionality provided by the API. Here are a few pointers that will cause developers to shout your praises rather than curse your name:

• Error messages/Exceptions should be clear
• Design patterns should be consistent
• Documentation should be useful

I’ll spend a little more on each topic to flesh out what I mean.

Error messages should be clear

Whether your language uses exceptions or another method of notification; the user of your API needs to know if they are the cause of the problem, and more importantly what they can do to fix it. Let’s take the example of bad parameters. They happen, particularly when a user doesn’t understand what is written in the API docs or it’s just an honest mistake. When a function has a half dozen parameters, it really helps to know which parameter is causing the problem. A generic “invalid parameter exception” with no indication of which parameter isn’t very helpful. If the parameter has to be within a certain range, say so.

There’s nothing more frustrating than spending a whole day trying to figure out what you are doing wrong, searching forums for possible clues, only to turn up empty. The more you can help your users (the developer) stay focused on writing software, the better. If an exception is caused by something outside of your control, it really helps to give that information back to the developer. They may be able to fix something that your library depends on.

Design patterns should be consistent

Whether you are using formal design patterns or simply a programming idiom to help convey the intent of the API, use it the same way throughout your API. There is nothing more confusing than having exceptions to the rule. We get enough of that learning English, we don’t need it in our APIs as well. The problem with exceptions is that they raise the mental complexity of the API. Every time a developer accesses a function, they have to consider is this function operates differently (or worse: which difference applies here?).

There’s no question that designing a consistent API is very difficult. The nature of the problem is trying to find an abstraction that helps the developer solve a problem. The problem is that if you choose the wrong abstraction you will make it harder to solve the problem or write the API. It’s a delicate balance. However, if you find yourself always needing to break your abstraction in a couple of places, perhaps you chose the wrong one to begin with?

Documentation should be useful

Developers really need two types of documentation. Many API writers recognize the importance of API docs (such as JavaDocs or .Net Docs). In order for these to be useful, the person referring to the documentation needs to know more than the parameters and the name of the function. They need to know what the function does for them, and if there are related functions that handle different tasks what they are. In an API reference, that is sufficient. You just need to refresh the developer’s memory, and help point them in the best direction if there are related (but different) functions.

What usually gets lost is describing the design patterns or abstraction the API is using. It’s one thing to know what the functions are, it’s quite another to be able to put them together in the right combination. Writing down the API design approach also helps the API developers understand how they are supposed to be solving the problem. Also, by writing down the API approach, you see just how difficult it is to convey. If it is too hard to explain, it is too hard to understand, and far too hard to use. Without this foundation, the examples of how to use the API make a lot more sense.

Conclusion

The three concerns I listed here are the top frustrations I have with any given platform. Whether it’s Java’s extensive APIs, the .Net library, Ruby’s API, etc. I’ve come across violations in at least one of the three concerns. My biggest frustration at the moment has to deal with bad or confusing error messages. The worst thing you can do as an API writer is have your users play “bring me a rock” with your API. It really helps to know that parameter X is invalid because it is not within the range of Y-Z. It does not help to know that at least one parameter in a list of seven is invalid: go figure out which one and how to fix it yourself. Additionally, if the network gets dropped and you no longer have a connection to a server, that information needs to make it to the developer instead of other exceptions that are just a consequence. For example if the problem is a file permissions problem, throwing a null pointer exception only confuses the user. They will quite rightly think you don’t know what you are doing. Understandably, proper exception handling is important. Which exceptions do you expose, and which do you handle internally? When the system breaks are you doing something unexpected as a fail-over? Java’s Remote Method Invocation API failed terribly in this manner. Instead of completely failing to call the remote object, it would silently fail over to an unencrypted HTTP tunneling approach first—even if the original connection was encrypted. That’s an epic security failure. Be reasonable, and sometimes it is better to fail completely than it is to fail over to something insecure without notifying the developer in any way.

I‘m going to be as blatantly honest as I know how to be. Writing good documentation is hard . This post is inspired by FransBouma who in turn responded to Jeremy D. Miller. At the center of contention is the role of documentation, and whether it is kosher to assert that a TDD unit test counts as documentation. Now, my focus isn‘t adding fuel to the fire, but rather looking at the bigger problem.

Let‘s consider first and foremost that everyone seems to agree that there should be some level of documentation. What’s at stake is not whether we have documentation but rather its form and content. We also are aware that instinctively, we software engineers stop managing traditional word processing documents at the first opportunity. We do this because we know that it really doesn‘t have any immediate usefulness, and thinking about what the maintainers will have to face when the boss is breathing down your neck is the last thing on your mind.

Let‘s recognize the contributions to documentation that agile processes and TDD have brought to the table. By recognizing that many documents only have ephemeral (temporary) value, we don‘t have to maintain them for posterity. Also by realizing that documentation is painful to write, they try to instill a practice that kills two birds with one stone: some documentation is better than no documentation, and documentation that can pull double duty and check your code has immediate payoff. Granted, traditional unit tests are written in the language of the code you are testing. It requires a certain a priori (pre-known) knowledge to understand the tests. You have to know the language that the tests are written in, which is usually a safe bet because we are testing in the same language we are writing. You can argue till you are blue in the face about whether or not you can consider it a form of documentation, but it does provide the assertions that the working code must obey. That is, at the very least, a useful amount of information that works in our advantage.

So what kind of documentation is useful? I mean it‘s all fun to argue about the virtues of documentation when we haven‘t even begun to discuss what makes a good document. Have you ever seen a 17 volume specification with reams of paper having diagrams, text, and what not? Something like that is utterly useless. The last time I was asked to review something like that (we all took sections), we gave our input, and with each iteration we found that the documentation was never changed to reflect our concerns from the last time. What does this tell you about the purpose of a 17 volume design spec? It‘s only purpose is to throw so much crap at the client they will simply sign on the dotted line instead of actually validate that you did what you said you were going to do. That is not useful to anyone. Not to product maintainers, not to people writing the software, and definitely not to nontechnical people.

Here is a short list of guidelines for good technical documentation:

• It should be focused on one thing. Don‘t try to use the same document to tell people how the software is designed, how to perform system administration, and how the process is done. These are all separate documents with separate audiences.
• If you have to think about it hard, you have to write it down. At the very least write down your final decision. Typically, these are the things that will catch people by surprise.
• If it‘s a surprise to you, it will be a surprise to someone else. How to write a Google Nest is a perfect example of what I mean.
• How Tos are better than “what it is”. Maintainers need to know how to do something, not what its structure is.

There is some value to writing down the pros and cons as to why you chose a specific solution over another, but at the end of the day, most people don‘t really care. Sure there is some academic value to it, but a decision usually is the best of what was known to be possible at the time. Times change, and so does what solutions are available. It could be that you abandoned a design path because the underlying technology hadn‘t caught up to your vision yet. For day to day tasks, the bullets I listed above are more useful.

Now, what form should documentation take? Should we break out our word processor and create a templated document? Maybe, maybe not. The key to evolving good documentation is to make it easy to do so. If you can incorporate the documentation, or key parts of the documentation, into the code, then you are effectively lowering the barrier to have developers maintain it. Of course, there is nothing wrong with using a good project wiki. I‘ve found that to be the best way to get ideas and information down, and move on. It isn‘t formal, and it is designed to be easily linked. That means it is easier to maintain. Of course, passing the wiki on to the maintainers is the next challenge — but there are solutions for that already.

Technorati Tags: documentation, design

Let me say right off the bat that I am a Ruby fan, and I love Ruby on Rails. In so many ways the API just feels right for the type of applications I write. However, there is one area that Ruby and Rails is still playing catch up in, and it has to do with the relative size of the community. Let‘s face it, for all its benefits, Ruby on Rails is still a small player in the world of web application development and it enjoys a very enthusiastic, yet small, community of developers. In a way it is my continuation on the rants on M$ development. The main problem is that there still isn‘t enough people who like to share how they did things. I don‘t believe that it has to do with the same motivation as Micro$oft, because both Ruby and Ruby on Rails are open source efforts and don‘t seek monetary reward. I‘m sure they wouldn‘t refuse it if it was offered though….

In a way I believe that because there is this general feeling of the fact that everything is “so easy a caveman can do it” (apologies to any cavemen reading this). Why should I write about something that everyone and their brother can do? To answer that question I have to ask a counter-question, why is my article on role based authorization my most popular article I‘ve ever written? The problem with Ruby is that there are so many ways to do something that sometimes you get stuck trying to figure out what is the best way for your project. I applaud the efforts for writing plugins and “acts_as” filters, but how do we use them or write them?

I‘m not saying that there is no documentation, because the people who maintain Ruby on Rails have done a wonderful job in this area. The problem is that it is only them writing any decent documentation. I‘m glad that they set up a Wiki, as it contains some key information such as how to connect to SQL Server (not that I would ever recommend using that) or deploy on different servers. The problem is that it suffers the same fate of most Wikis (with Wikipedia the shining exception), disorganized mess with articals of varying quality and completeness. Ironically, some of the better introductory guides or howtos come from curious Java guys.

Perhaps if there was some outlet to stroke people‘s ego or let them become de facto gurus in a publication the world may change a bit. So far the only thing that resembles a regular (English) publication in the Ruby world I am aware of is the Ruby on Rails Podcast. As great as that is, there is still a dearth of spreading knowlege about how to solve some pretty cool problems. As a result, it‘s easy to get stuck.

I would seriously consider setting up some sort of publication, even if it is strictly online, if I could be reasonably sure that I could have recurring articles of decent quality. Perhaps you can consider this a feeler for the level of interest here. I can‘t give remuneration for article submissions at this time, but I would seriously like to do something like this. It would be even better if the host site was implemented in Rails. If you are interested, post a comment here. If I get underwelming silence then the idea fades away. If I get an overwelming response, then I would move forward. I would have a need for recurring articles as well as one-off how-tos and reviews.