Channels ▼

Christopher Diggins

Dr. Dobb's Bloggers

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.
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. 
  1. Document everything, but don't rely on documentation to explain things
  2. Test your assumptions, don't just crash on bad data (e.g. handle null pointers gracefully)
  3. Don't assume your users are professionals, or experts in a domain. 
  4. 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. 
  5. Make common tasks easy and intuitive (e.g. single function calls, or throught helper functions)
  6. Make things strongly typed: don't just use integers everywhere. Use types to distinguish different kinds of values.
  7. Provide multiple template projects that people can build from
  8. 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. 
  9. 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. 
  10. 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

Currently we allow the following HTML tags in comments:

Single tags


<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags


<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

