API design

In the past programming was more about writing from scratch - now code reuse take more and more prominent place in development. In the Perl sphere this is clearly visible in the growth of CPAN, but what is also visible is that this quantity is not everything.

There are many aspects of quality - here I would like to focus on the APIs. The problem with APIs is that their shortcomings are much more subtle than let's say bugs. Many of them are just inconveniences - things that you stop to see once you get accustomed to them, and all of them require some experience or theory just to understand that it can be done better. Arguments about APIs can become dangerously subjective. We are in dire need of API theories, objective measures to evaluate them - and here I try to compile a list of on line resources on that subject.

How To Design A Good API and Why it Matters (from Google Tech Talks)"

- see also an ACM paper with the same title and a nice abstract in the form of bullet points.

My take-away points (the most non-obvious or potentially useful in arguments):

• write examples from the very start and build the API from use cases
  
• good names are important - API is language
  
• "when in doubt leave it out"
  
• implementation somtimes leaks out to the API
  
• for inheritance document self-use pattern (how methods use one another)
  
• "don't make the client do what the module can do"
  
• you can't please everyone so aim to displease everyone equally.
  

The Little Manual of API Design

Characteristics of good design:

• Easy to learn and memorize
  
• Leads to readable code
  
• Hard to misuse
  
• Easy to extend
  
• Complete
  

Again stress on writing use cases and code using the API during the design process - and one surprising but seemingly valid point: "prefer specific names to general names".

API Design Matters

This one is mostly arguing why API design matters - but there are a few points worth noting:

• always design the API from the perspective of the caller (rather obvious)
  
• again start with use cases
  
• there used to be much more programming from scratch - now we use more libraries and designing API becomes more and more important, but this is not yet reflected in university curricula (this is exactly the intuition that led me to this blog post)
  

Designing and Evaluating Reusable Components

The needs of the programmer changes as her project proceeds and it is important to account for that fact when writing the API. In particular more advanced projects usually need more granular APIs while at the beginning they are only an obstacle.

API design guidelines

- my question on Reddit.

Update: Read Curing Python's Neglect - it's not really about Python in my opinion - and it is about how people get used to bad APIs and stop noticing the ugliness of them.