What are best practices for developing consistent libraries?

Question

I am working on developing a pair of libraries to work with a REST API. Because I need to be able to use the API in very different settings I'm currently planning to have a version in PHP (for web applications) and a second version in Python (for desktop applications, and long running processes). Are there any best practices to follow in the development of the libraries to help maintain my own sanity?

Answer 1

Well, the obvious one would be to keep your naming consistent. Functions and classes should be named similarly (if not identically) in both implementations. This usually happens naturally whenever you implement an API separately in two different languages. The big ticket item though (at least in my book) is to follow language-specific idioms. For example, let's assume that I were implementing a REST API in two languages I'm more familiar with: Ruby and Scala. The Ruby version might have a class MyCompany::Foo which contains method bar_baz(). Conversely, the Scala version of the same API would have a class com.mycompany.rest.Foo with a method barBaz(). It's just naming conventions, but I find it goes a long way to helping your API to feel "at home" in a particular language, even when the design was created elsewhere.

Beyond that I have only one piece of advise: document, document, document. That's easily the best way to keep your sanity when dealing with a multi-implementation API spec.

Answer 2

So, the problem with developing parallel libraries in different languages is that often times different languages will have different idioms for the same task. I know this from personal experience, having ported a library from Python to PHP. Idioms aren't just naming: for example, Python has a good deal of magic you can use with getters and setters to make object properties act magical; Python has monkeypatching; Python has named parameters.

With a port, you want to pick a "base" language, and then attempt to mimic all the idioms in the other language (not easy to do); for parallel development, not doing anything too tricky and catering to the least common denominator is preferable. Then bolt on the syntax sugar.

Answer 3

'Be your own client' : I've found that the technique of writing tests first is an excellent way of ensuring an API is easy to use. Writing tests first means you will be thinking like a 'consumer' of your API rather than just an implementor.

Answer 4

Try to write a common unit test suite for both. Maybe by wrapping a class in one language for calling it from the other. If you can't do it, at least make sure the two versions of the tests are equivalent.

Answer 5

AFAIKT there are a lot of bridges from to scripting languages. Let's take e.g Jruby, it's Ruby + Java, then there are things to embed Ruby in Python (or the other way). Then there are examples like Etoile where the base is Objective-C but also bridges to Python and Smalltalk, another approach on wide use: Wrapping C libraries, examples are libxml2, libcurl etc etc. Maybe this could be the base. Let's say your write all for Python but do implement a bridge to PHP. So you do not have that much parrallel development.

Or maybe it's not the worst idea to base that stuff let's say on .NET, then you suddenly have a whole bunch of languages to your disposal which in principal should be usable from every other language on the .NET platform.

Answer 6

why not use python for web applications too? there are several frameworks available: django, web2py - similar to django but many say it's simpler to use, there is also TurboGears, web.py, Pylons

along the lines of bridging - you could use interprocess communication to have PHP and python application (in daemon mode) talk to each other.