&gt;  So... what is an example of a well written API&#x2F;SDK?<p>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.<p>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.<p>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 &quot;wow, this horrible notation obscures the simple ideas at the centre of the paper.&quot;<p>Incidentally, I still think that the notation is better than the original; but the main thing that I&#x27;ve learned is to do it yourself before you complain about what someone else has done—after which (a) you&#x27;ll have a good implementation and won&#x27;t need to complain, or (b) you&#x27;ll feel much humbler and won&#x27;t want to complain.