A lesson on APIs and Documentation

After a day struggling with something that didn’t quite work the way I thought it would, here are a few thoughts on how we can make the world a better place when writing libraries, Open Source or otherwise.

  • Always provide API-level documentation, especially explaining the side effects of functions or parameter values
  • Provide several examples on a knowledge base
  • Consider how to package debuggable code (sources etc) when packaging up your libraries – sometimes not being able to debug something is most of the problem
  • Provide logging or methods of getting a trace to see what’s happening
  • All your data might be representable as a simple list inside your class, with helper methods extracting suitable values, but this makes it harder to see what state the object is really in when debugging
  • If you struggle for several hours to debug something and discover something that would be useful for others to know, then find a way to share that back with everyone

Most importantly, learn from the things which were hard. I think knowledge gained from this situation is most probably best pushed back into:

  • Code – variable and method names
  • Code documentation – Javadoc etc
  • Knowledge bases and examples – wiki etc

If we share the knowledge we gain and make things easier to know in future, then all libraries will tend towards perfection.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s