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.