API Design, part I

API Design might to some not be the coolest thing around, but if you ask me it's extremely important. A few months ago I was playing with it a little and came up with a list that is inspired by the Agile Manifesto:

API design manifesto
  • Code over comments
  • Immutability over mutability
  • Testability over encapsulation
  • Context over generality
  • Small and simple over completeness
  • Backward compatibility over revolution
  • Encapsulation over transparency
I know, I need to explain my thinking for each line above. I think I'll put it into a series of blog posts, but first I'd like to improve the list. A few weeks ago I discussed this topic with a couple of friends at a workshop and I got loads of ideas about how to improve it. Before starting the work I also wanted ask around here for even more input. If you have ideas, please email me: jimmy dot nilsson at factor10 dot com.