Great article in the ACM Queue on good and bad API Design
To me, the most pertinent comment is on the fact that programming has changed over the last twenty years (you wouldnt implement your own private version of bsearch() or qsort() any more), CS education still does not teach anybody
how to decide whether something should be a return value or an out parameter, how to choose between raising an exception and returning an error code, or how to decide if it might be appropriate for a function to modify its arguments
Must read!