株式会社クリアコード > ククログ

ククログ


APIデザインケーススタディ

2015年12月に技術評論社から「APIデザインケーススタディ――Rubyの実例から学ぶ。問題に即したデザインと普遍の考え方」というライブラリー作成者(=APIを設計する人)向けの本が出版されました。

APIデザインケーススタディ ~Rubyの実例から学ぶ。問題に即したデザインと普遍の考え方 (WEB+DB PRESS plus)
田中 哲
技術評論社
¥ 3,002

内容

本書は「事例紹介」→「その事例から得られる、APIを作るときの方針」という流れを繰り返します。

「APIを作るときの方針」では「既存の知識とあわせると使いやすいAPIになる」や「変な使い方をできないようにすると使いやすいAPIになる」、「ユースケースに合わせると使いやすいAPIになる」といったことを挙げます。「事例紹介」の後なので、「方針はわかったけど具体的にどうすればいいの!?」となりにくいです。

全編を通して「事例紹介」→「方針紹介」という一貫した流れをとっていることが理解しやすさを助けています。この理解しやすさを助ける一貫性は、著者の「使いやすいAPIにするにはどうしたらよいか」という知見からきているのかもしれません。

話が逸れてアレですが、リファレンスマニュアルや仕様書など(たぶん論文も)の正しく伝えることが重要な技術文書は、小説や感想文などの読み物の文書と違い、「同じことは同じように書く」ことが効果的です。

たとえば、「関数AはBを受け取りCを返します」と説明するなら、他の関数も「関数xはyを受け取りzを返します」と書くということです。「yを渡されたらzを戻すのが関数xです」というように書き方を変えないということです。同じように書いていれば同じことだということがすぐにわかるからです。(読み物の文書は何度も同じように書くと飽きることがあるので同じようなことを違う言い回しで書いたりします。)

本書は一貫した流れになっているので、読み進めるうちにパターンがわかって理解しやすくなっていくでしょう。

本書の多くは著者が実際にやったことを事例として紹介しています。読むと、「たしかにこの事例だとこういうAPIがよさそうだなぁ」という気持ちになるでしょう。たまに「ここまでやるのか!」という気持ちになることもあるでしょう。自分もそこまでやるかはケースバイケースでしょうが、ここまでやられると「そのAPIがよさそう」という気持ちになるというのは知っておくと役に立つでしょう。役に立つのは、自分がだれかにAPIを提案したりだれかが使うAPIを作ったりするときです。

なお、「さまざまなタイムゾーン」というコラムを読むと「うん!わかった!わかったから!」という気持ちになれます。

最後に、本書の日本語の文ですが、もしかしたら、読む人によっては助詞の使い方で読むときにつまる人がいるかもしれません。たとえば、「このときに読み出したデータは捨てることはできません。」(19ページ。「1.02 feof関数とIO#eof?メソッド」)が気になるならつまるかもしれません。(気になる人は「このときに読み出したデータを捨てることはできません。」か「このときに読み出したデータは捨てられません。」ならどうでしょうか。)

まとめ

ライブラリー作成者(=APIを設計する人)向けの本、「APIデザインケーススタディ――Rubyの実例から学ぶ。問題に即したデザインと普遍の考え方」を紹介しました。ライブラリーを作っている人は読んでみてはいかがでしょうか?ライブラリーを作っていない人は読み物として読んでも案外おもしろいかもしれません。話題が多岐にわたっているので「へぇ、こんな世界があるんだぁ」という気持ちになれます。

2016-01-25

«前の記事: ワークライフバランス推進の取り組み 最新記事 次の記事: C/C++のソースコードをCppcheckで静的解析してみよう»
タグ:
年・日ごとに見る
2008|05|06|07|08|09|10|11|12|
2009|01|02|03|04|05|06|07|08|09|10|11|12|
2010|01|02|03|04|05|06|07|08|09|10|11|12|
2011|01|02|03|04|05|06|07|08|09|10|11|12|
2012|01|02|03|04|05|06|07|08|09|10|11|12|
2013|01|02|03|04|05|06|07|08|09|10|11|12|
2014|01|02|03|04|05|06|07|08|09|10|11|12|
2015|01|02|03|04|05|06|07|08|09|10|11|12|
2016|01|02|03|04|05|06|07|08|09|10|11|12|
2017|01|02|03|04|05|06|07|08|09|10|11|12|
2018|01|02|03|04|05|06|07|08|09|10|11|12|
2019|01|02|03|04|05|06|07|08|09|