API Design Matters http://queue.acm.org/detail.cfm?id=1255422

http://d.hatena.ne.jp/oraccha/20090606/1244225100 経由で。

C# の Select() 関数についてひとしきり文句を書いた後に、実際良い API を作るコツを挙げている。

API は必要な機能を備えろ

タイムアウトが 35 分以内で無ければならないとか、微妙な制限があってはならない。

API は不便を感じない限り出来るだけ小さく

例えば UNIX で wait, waitpid, wait3 wait4 と色々あるのはやり過ぎ。wait4 だけでよい。微妙に似た関数が沢山あって、一つの一般的な関数で他の奴が実装出来ない作りになってるのが最悪なパターン。

文脈なくして API なし

キーから辞書を引いて文字列を返す関数を考える。キーに対応する文字列が無かった時、次のやり方があるだろう。

• 例外発生
• null を返す
• 空文字列を返す

どれが正しいかは、その関数が使われる状況によって違う。null と 空文字列の区別が不要なら、空文字列を返すのが便利だろう。

一般的な API は中立に、特殊な API はおせっかいに

上記の文脈の話の続き。低レベルな API では選択をユーザに委ねる。

API の設計は使う身になって

ソースコードを読むだけで意味が分かるように設計する。例えば真偽値の代わりに enum を使って定数に名前を付ける。

API は責任転嫁するな

API を使うために必要な条件を色々作るな。例えばメモリ管理は自分で行え。ユーザにメモリを割り当ててもらってポインタ渡しというのは、速くなりそうに見えるが、全体のコストは変わらないのでややこしくなるだけ無駄。

API のドキュメントは実装する前に書け

実装してしまった後ではプログラマの頭は実装に毒されていて、自明でない前提やなんかを忘れがちだ。むしろ、実装する前に、それも実装者ではなくユーザにドキュメントを書いてもらうべき。

良い API は人間工学的である

関数名や引き数の型や順序に一貫性を持たせるべき。

... 作者は当時 47 歳だそうだが、この後、世の中に酷い API がはびこる理由として、プログラマが年を重ねるとマネージャになってしまい経験を設計に行かせられないからだ！というような事が書いてある。しかし私の経験から言うと、歳を取るのと良い API を書ける事の間に相関性は無いと思うんだけど、どうだろう。若くても他人のコードをよく読んでる人は API の設計も上手だと思う。