API-Design ist sicherlich keine einfache Sachen, aber es gibt schon ein paar Grundregeln, an die man sich relativ problemlos halten kann. Ein gute Auflistung dieser Regeln liefert z.B. der Blog Eintrag “API Design Guidelines”.

Einer der wichtigsten Punkte wird im genannten Text unter “Be intuitive” aufgeführt: “Use consistent parameter ordering across methods”. Dazu ein Beispiel aus der C API, über das ich heute dank Segfault gestolpert bin:

int puts(char *s);
int fputs(const char *s, FILE *stream);

vs.

int printf(const char *format, ...);
int fprintf(FILE *stream, const char *format, ...);

fprintf erwartet den Stream als erstes Argument, während fputs ihn als letztes Argument erwartet. Nicht gerade konsistent und intuitiv. Und das ganze geht noch weiter: puts ist ja vor allem so praktisch, weil es sich selbst um das Newline-Zeichen kümmert. Warum kann fputs das dann nicht auch? “fputs() schreibt die Zeichenkette s ohne sein nachfolgendes ’’ in den Ausgabestrom stream.” (aus der Manpage).