Open-source, Software

Open Source and Constraints

“My code improves far more from writing documentation than writing tests. Documentation forces you to approach your APIs symmetrically.”

http://kennethreitz.org/open-source-and-constraints.html

Advertisements

2 thoughts on “Open Source and Constraints

  1. I pretty much agree. But I think it can be better summed up by saying, “Think about what API you’d like to work with if someone else had written it. Further, think about the information you’d like to know before attempting to use the API.”

    If you ask yourself these two questions as you’re developing your API, then the API should be much easier to use and the documentation should almost write itself. At the very least, it should lead to inline documentation that can be parsed with Doxygen which will actually be usable by other people (i.e. _not_ the Groovy/Grails documentation).

    A project that I think does this well is AFNetworking (https://github.com/AFNetworking/AFNetworking). On the other end, we have libssh2 (http://www.libssh2.org/). Both are great APIs (for the most part), but only one is a joy to use; and it’s not the one with shitty documentation.

    Like

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s