10 Rules for writing Good SDKs
July 23, 2009
I have worked with dozens of libraries, frameworks, and SDKs over the years. In my day job my primary responsbility is to document SDKs for Autodesk, such as for 3ds max and Mudbox. Today I am going to provide 10 ruoles for writing a good SDK for extending an application.
I have worked with dozens of libraries, frameworks, and SDKs over the years. In my day job my primary responsbility is to document SDKs for Autodesk, such as for 3ds max and Mudbox. Today I am going to provide 10 ruoles for writing a good SDK for extending an application.
An application can really boost its audience and scope by providing an SDK for developing plug-ins. The difference between a good plug-in SDK and a bad one, can make a huge difference in the productivity of users.
A good SDK can really make an application shine, because the user community can contribute new features and functionality to the core application, and helps make the user base very loyal. On the other hand a poor SDK may give the impression that the host software is unstable or untested, when in reality it is misbehaved plug-ins that are the problem.
But you can't blame the plug-in developers if your SDK is hard to use, fragile, and poorly documented! So here are some rules for writing good SDKs.
- Document everything, but don't rely on documentation to explain things
- Test your assumptions, don't just crash on bad data (e.g. handle null pointers gracefully)
- Don't assume your users are professionals, or experts in a domain.
- Use the same terminology in the SDK as that used in the software itself and don't use abbreviations. Most people have tools that do auto-completion nowadays.
- Make common tasks easy and intuitive (e.g. single function calls, or throught helper functions)
- Make things strongly typed: don't just use integers everywhere. Use types to distinguish different kinds of values.
- Provide multiple template projects that people can build from
- Use your own SDK as much as possible. When adding new features to the application, first look to see if the SDK can be used.
- Don't directly expose implementation details: the SDK requires an extra layer of abstraction that makes the steps for developing basic plug-ins easy and obvious.
- Make it obvious how to achieve a desired outcome: reduce ambiguity and complexity. In other words: don't give the users enough rope to hang themselves (or your application) otherwise they will.
Related Reading
More Insights
INFO-LINK
 |
To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy. |
