人気のAPI／フレームワークを作るための39カ条：安藤幸央のランダウン（35）

「Java News.jp（Javaに関する最新ニュース）」の安藤幸央氏が、CoolなプログラミングのためのノウハウやTIPS、筆者の経験などを「Rundown」（駆け足の要点説明）でお届けします。（編集部）

[安藤幸央（yukio-andoh@exa-corp.co.jp），＠IT] PC用表示関連情報

LINE

Hatena

いま人気のAPI／フレームワークはなぜ誕生したのか？

　Javaを取り巻く開発環境は、さまざまなフレームワーク、API（Web APIを含む、Application Programming Interface）に囲まれています。

　Javaに限らず、普段さまざまな言語で開発を行っていて、「こんなAPI群があれば便利なのに」「こんなAPIを作ってみたい」という要求がわき起こることはないでしょうか？

　API（以下、フレームワーク・Web APIも含む）の利用範囲は、社内で使うものから、オープンソースで公開するものまでさまざまな形態が考えられます。APIの誕生の発端はいろいろありますが、以下のようなものが考えられます。

APIの誕生の発端

ある仕様を利用するための網羅性の高いライブラリを用意したいとき
再利用性が高い（と思われる）プログラムをライブラリ化したいとき
Webシステムを外部から利用してもらうために一部分を公開したい場合
多人数で開発する事柄で共通化させておきたい部分をまとめたい場合
ほかの言語で作られたアプリケーションをある言語で利用したいときの橋渡し用

　ちなみに、JSP／Servletの世界でよく使われているStruts Frameworkは開発者のCraig McClanahan氏が休暇中に思い付いて開発したものだそうです。オレゴン州のビーチで、ラップトップに向かい、3日間の休暇中ずっとコーディングしていたそうです。

　一緒に行った奥さんは機嫌が悪かったようですけど。

　ここでは、作成したAPIが自分だけではなく、多くの人に使ってもらえるよう、便利に使えるポイント、広く普及するためのポイントをとらえていきましょう。

API設計のポイント

　開発したAPIを数多くの人に活用してもらおうと思った場合、APIの機能や性能以上に大切な事柄がいくつかあります。

　自分がよく利用しているフレームワークやAPI群には、共通したある要素があることが再認識できるでしょう。

人気のAPIにするための26カ条

利用するために覚えることが少なくて済むこと
頻繁に使うものは、デフォルト値で簡単に使えること
頻繁に使うものは、できるだけコンパクトにまとめること（多機能になり過ぎないように）
頻繁に使うものは、できるだけ短い名前で。あまり使わないものは、逆に長い名前でもよい
頻度の低い細かな機能や、詳しい人は深いところまで細かく設定して使えること
できるだけ簡単に。できるだけソースコードを書く量は少なくて済むこと
無駄な繰り返し、設定などを記述しなくても良いようにする
同じ機能を持つものが複数個所にあると混乱する。統一・統合を考える
統一された設計思想の下に作られ、少し慣れると、使い方が予想できること
各API、メソッドの名前に統一感がある。欲しい機能名が予想できること
規格を網羅しようとするために、複雑になり過ぎてはいけない。よく使われる機能は2割程度
UNIXコマンド名や、Javaのクラス名など連想しやすい機能名を付けるのも1つの方法
必要な機能がそろっていること。重要な機能が未完成だと、以降、使ってもらえなくなる
大量のソースコードの中でも読み取りやすい（あるAPIの一部であることが認識しやすい）こと
コードが読みやすいことが第一。文字数を少なくするために読みやすさを犠牲にしてはならない
何がデフォルトであるのか、が明確に分かること。True／Falseでは、一瞬どちらがどちらだか分かりにくい
内部実装やパフォーマンスチューニングにAPIそのものの機能が影響を受けないこと
メソッド名などに、ほかのライブラリと同じ名前が混在すると混乱する。クラス／パッケージの扱いとともに、明確さが重要
バージョン管理の一貫性。後方互換、上位互換に関して明確な指針があること
統一されたパッケージでまとめられ、ほかのパッケージ（ライブラリ）と衝突しないこと
ある特定のマジックナンバー（1番が何、2番が何、……）を使わないこと。覚えなくてもよいこと
定番の省略形があったり、多少長いと感じても、フルスペルで命名すること。ヘタな省略形を使った命名だと、時間がたつと誤解されたり、訳が分からなくなる場合が多い
APIの宣言部分（関数やクラスの冒頭）に必要最低限のAPIドキュメントを記述しておく。ソースコードを見ただけで、ある程度のことを把握できるようになる。多数を拾い読みするときに便利
エラーメッセージは、どこで何が起こったのか、原因と思われる事象は何なのかを明らかにする。ダメだったことだけをエラーレポートするのでは、意味がない
開発者が記述しなければいけないエラー処理用のコードは最低限で済むように
例外処理用のコードは、開発者が記述しようとする例外を阻害しないように

APIドキュメントの充実度も重要

　新しい、初めてのAPIを利用するかしないかといった判断をする場合、ドキュメントの充実度も重要な要素になってきます。

　世の中には、Ajax用のPrototype.jsのように、ソースコード中に解説が書かれ、公式ドキュメントがまったくない変わった例もありますが、大抵の場合、ドキュメントの充実度は、APIそれ自身の完成度にも大きくかかわってきます。

APIのドキュメントを充実させるための7カ条

チュートリアルやサンプル、レシピが充実していると、使い始めやすくなる
概要を知りたい人向け、初心者向け、上級者向け、開発者向けと分類分けしてあるとよい
概要が完結に書かれており、ほかの人や上司に説明しやすいものがあるとよい
設計思想、デザイン思想を記したドキュメントがあると便利
開発におけるテストに関するポリシーや、パフォーマンスに関する考察などがまとめられているとよい
リファレンスマニュアルが充実しており、逆引きなど、利用者が情報にたどり着きやすいこと
既知のバグがあった場合、バグ修正よりも早い段階でバグ報告がなされていること

APIを取り巻くそのほかの要素

　多くの人にAPIを利用してもらいたい場合、APIそのものの出来や性能のほかにも、数多くの要素が重要視されます。流行のAPIとなるためには、APIそのものの出来だけでは普及しないのです。

人気のAPIにする付加要素の6カ条

ネーミングはとても大切である。覚えやすい名前であること、Googleで検索しやすい、一般的ではない単語、ほかにはない独自の名前であること、つづり間違いをしにくい単語名であることが重要が重要
（できれば）オープンソース化されており、ライセンス形態が明確になっていること
APIを利用する開発者間でコミュニティが形成されていること
（ノウハウを蓄積した人がいる、利用者が多いといった安心感が得られる）
開発者、開発チームへのフィードバックが受けられる場（連絡先）、雰囲気があること
頻繁にバージョンアップされており、開発版と安定版が明確に分かれていること
将来のロードマップが明らかにされており、今後の発展や、将来性が感じ取れること

API普及への道のり

　世の中には数多くのAPIがあり、オープンソースのものから、企業が製品として販売しているものまでさまざまなものが存在します。

　APIを組み合わせて開発する場合、そのAPIの枠組み以上には自由度がなくなる弊害に陥りがちです。新たな発想が閉じ込められてしまわぬよう、自由な発想の下にアイデアを実現するのが理想です。

　便利なAPIを見つけ、便利なAPIを開発し、便利に活用していきましょう。

そして、40カ条目は……

　もし、40カ条の方がキリがよいと思われる方がいれば、ぜひご自分のノウハウを1つ加えるようにしてみてください。

　次回は、9月初めころに公開の予定です。内容は未定ですが、読者の皆さんの興味を引き、役立つ記事にする予定です。次回もどうぞよろしく。

プロフィール

安藤幸央（あんどうゆきお）

1970年北海道生まれ。現在、株式会社エクサマルチメディアソリューションセンター所属。フォトリアリスティック3次元コンピュータグラフィックス、リアルタイムグラフィックスやネットワークを利用した各種開発業務に携わる。コンピュータ自動彩色システムや3次元イメージ検索システム大規模データ可視化システム、リアルタイムCG投影システム、建築業界、エンターテインメント向け3次元 CG ソフトの開発、インターネットベースのコンピュータグラフィックスシステムなどを手掛ける。また、Java、Web3D、OpenGL、3DCG の情報源となるWebページをまとめている。

ホームページ
Java News.jp（Javaに関する最新ニュース）

所属団体
OpenGL_Japan (Member)、SIGGRAPH TOKYO (Vice Chairman)

主な著書
「VRML 60分ガイド」（監訳、ソフトバンク）
「これがJava だ! インターネットの新たな主役」（共著、日本経済新聞社）
「The Java3D API仕様」（監修、アスキー）