> So... what is an example of a well written API/SDK?
I think that this is an underrated question. I am not a programmer, but a mathematician; I will write from my experience in that field.
I was trying to understand a paper which used horrible, ad hoc notation that obscured the simple ideas at its centre. I invented a new, harmonious notation that beautifully revealed these simple ideas, and wrote a paper using it.
The notation was beatiful and harmonious as long as you were its inventor, and it was the most recent thing that you had been thinking about. Now, when I go back and read that paper … I think "wow, this horrible notation obscures the simple ideas at the centre of the paper."
Incidentally, I still think that the notation is better than the original; but the main thing that I've learned is to do it yourself before you complain about what someone else has done—after which (a) you'll have a good implementation and won't need to complain, or (b) you'll feel much humbler and won't want to complain.
Or maybe, the takeaway is: revisit your work later, when it's no longer fresh in your mind :) You'll understand what the strengths and weaknesses of your new design are, and are better placed to make an improved iteration.
Incidentally, writers have been doing this for years with drafts and editing. We definitely need to do that with our APIs and designs (aka. more incremental refactoring).
> We definitely need to do that with our APIs and designs (aka. more incremental refactoring).
Not with APIs we've shipped. Then it becomes breaking changes that appear pointless to others. Even when it's logically worth it to go back and fix APIs, it's rarely worth it practically. If no one is using your APIs, then do whatever. If your APIs are popular, you might find yourself in "version next" limbo like so many major projects that redesigned and couldn't convince their users to follow.
You're absolutely right. FWIW, I think this iterative process should take place before publishing your API. Sometimes a design needs to 'sit' for a month or two and be used a bit before you realize its boundaries: what it does well, and what could be improved. If you're judicious about improvements (i.e. don't rewrite) you'll avoid the second-system effect and put out an API that'll be better than your first attempt. I realize that's not always possible.
.net's standard library assemblies are generally excellent. A little verbose, perhaps. And very occassionnally a "what were they thinking?" moment (like WebClient throwing an exception for a 404 response-- fixed in HttpClient.) But overall, excellent.
Good to hear. What are they using for configuration in the newer frameworks instead?
True, XMLHttpRequest was good for the world. My distaste for XML generally stems from some particularly bad experiences I have had working with XML configuration files meant for humans to modify and some particularly poorly-implemented tools for working with said files. :)
