良いまたは悪いAPIをどのように定義しますか？
バックグラウンド：
私は大学で「ソフトウェア制約」というクラスを受講しています。最初の講義では、優れたAPIを構築する方法を学びました。
本当に悪いAPI関数の良い例は、C＃のソケットpublic static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds);です。関数はソケットの3つのリストを受け取り、それらを破棄して、ユーザーがSelect()に供給する前にすべてのソケットを複製する必要があるようにします。また、サーバーがソケットを待機できる最大時間を設定するintであるタイムアウト（マイクロ秒単位）もあります。この制限は+/- 35分です（intであるため）。
質問：
- APIを「悪い」とどのように定義しますか？
- APIをどのように「良い」と定義しますか？
考慮すべき点：
- 覚えにくい関数名。
- わかりにくい関数パラメータ。
- 悪いドキュメント。
- すべてが相互接続されているため、1行のコードを変更する必要がある場合は、実際には他の場所の数百行を変更する必要があります。
- 引数を破棄する関数。
- 「隠された」複雑性によるスケーラビリティの低下。
- 使用できるように、APIのラッパーを構築するためにユーザー/開発者から要求されます。
API設計では、この基調講演が常に非常に役に立っています。
良いAPIを設計する方法とそれが重要な理由-Joshua Blochによる
以下は抜粋です。全体を読んだり、ビデオを見たりすることをお勧めします。
II。一般的な原則
- APIは1つのことを実行し、うまく実行する必要がある
- APIはできる限り小さくする必要がありますが、小さくはない
- 実装はAPIに影響を与えるべきではない
- すべてのアクセシビリティを最小化
- Names Matter–APIは小さな言語です
- 文書化の問題
- 宗教的に文書化する
- API設計決定のパフォーマンス結果を考慮する
- API設計の決定がパフォーマンスに及ぼす影響は現実的で永続的
- APIはプラットフォームと平和的に共存する必要がある
III。クラスデザイン
- 変異性を最小限に抑える
- 適切な場合にのみサブクラス化する
- 継承またはそれ以外の場合の設計と文書化
IV。メソッドデザイン
- モジュールにできることをクライアントに行わせない
- 最小の驚きの原則に違反しないでください
- すぐに失敗する-エラーが発生した後、できるだけ早くエラーを報告する
- 文字列形式で利用可能なすべてのデータへのプログラムによるアクセスを提供する
- 注意してオーバーロード
- 適切なパラメーターと戻り値の型を使用する
- メソッド間で一貫したパラメーターの順序を使用する
- 長いパラメーターリストを避ける
- 例外的な処理を要求する戻り値を回避する
正しく使用するためにドキュメントを読む必要はありません。
素晴らしいAPIの兆候。
多くのコーディング標準と 長いドキュメント 、さらに ブック（フレームワークのデザインガイドライン） がこのトピックについて書かれていますが、その多くはかなり低いレベルでのみ役立ちます。
味の問題もあります。 APIは、さまざまな流行のイデオロギーへの厳格な遵守により、どんなルールブックのすべてのルールにも従い、それでもなお悪用する場合があります。最近の原因はパターン指向であり、シングルトンパターン（初期化されたグローバル変数より少し多い）とファクトリーパターン（構築をパラメーター化する方法ですが、多くの場合、不要な場合に実装されます）が多用されています。最近、制御の反転（IoC）とそれに関連する爆発が、設計に冗長な概念の複雑さを追加する小さなインターフェースタイプの数の増加である可能性が高くなっています。
好みに最適な家庭教師は、模倣（たくさんのコードとAPIを読んで、何が機能し、何が機能しないかを見つける）、経験（間違いを犯し、そこから学ぶ）、思考（自分のために流行していることをするだけではなく、行動する前に考えてください）。
- 便利-まだ満たされていない（または既存のニーズを改善する）ニーズに対応します
- 説明が簡単-機能の基本的な理解は簡単に理解できる
- 問題ドメインまたは実世界のオブジェクトモデルに従います。意味のある構成を使用している
- 同期呼び出しと非同期呼び出しの正しい使い方。 （時間がかかるものをブロックしないでください）
- 良いデフォルトの振る舞い-可能であれば拡張性と微調整を許可しますが、単純なケースに必要なすべてのデフォルトを提供します
- サンプルの使用方法と実際のサンプルアプリケーション。これはおそらく最も重要です。
- 優れたドキュメント
- 自分のドッグフードを食べる（該当する場合）
- 1つの巨大な汚染されたスペースではないように、小さいままにするか、分割します。機能セットを区別し、依存関係がほとんどない場合は分離します。
もっとありますが、それは良いスタートです
優れたAPIには、それが説明するものに近いセマンティックモデルがあります。
たとえば、Excelスプレッドシートを作成および操作するためのAPIには、Workbook、Sheet、Cellなどのクラスと、Cell.SetValue(text)およびWorkbook.listSheets()。
優れたAPIを使用すると、クライアントは必要なほとんどすべてのことを実行できますが、多くの心のない忙しい仕事をする必要はありません。 「無頓着な仕事」の例としては、データ構造フィールドの初期化、実際のカスタムコードがない場合に変化しないシーケンス内のいくつかのルーチンの呼び出しなどがあります。
悪いAPIの最も確実な兆候は、クライアントがすべて自分のヘルパーコードでそれをラップしたい場合です。少なくとも、APIはそのヘルパーコードを提供しているはずです。最も可能性が高いのは、クライアントが毎回自分でローリングする抽象化のレベルを高めるように設計されているはずです。
私はいつもというタイトルのキュー内のこの記事が好きでしたAPI Design Matters
http://queue.acm.org/detail.cfm?id=1255422
また、このコラムでは、API設計の問題も扱います。
悪いAPIは、意図された対象ユーザーが使用していないものです。
優れたAPIとは、対象となるユーザーが設計した目的で使用するAPIです。
優れたAPIとは、意図した対象者が意図した目的で使用するAPIと、設計者が予期しない理由で意図しない対象者が使用するAPIです。
AmazonがそのAPIをSOAPとRESTの両方として公開し、RESTバージョンが勝利したとしても、それは根本的なSOAP APIが悪かった。
同じことがあなたにも当てはまると思います。あなたはデザインについてあなたが望むすべてを読んで、あなたのベストを尽くすことができますが、酸テストが使用されます。何が機能して何が機能しないかについてのフィードバックを得る方法を構築するのに少し時間を費やし、それを改善するために必要に応じてリファクタリングする準備をしてください。
優れたAPIとは、単純なものをシンプルに（最小限のボイラープレートと最も一般的なことを行うための学習曲線）、可能な限り複雑なもの（最大限の柔軟性、できるだけ少ない仮定）にするAPIです。平凡なAPIは、これらのいずれかをうまく実行するものです（非常に単純ですが、本当に基本的なことをしようとしている場合、または非常に強力ですが、非常に急な学習曲線など）。恐ろしいAPIは、これらのどちらもうまく機能しないAPIです。
これにはすでに他にもいくつか良い答えがあるので、言及していないリンクをいくつか投入するだけだと思いました。
記事
書籍：
適切なAPIでは、カスタムIOと、該当する場合はメモリ管理フックを許可する必要があります。
典型的な例は、ディスク上のデータ用のカスタム圧縮アーカイブ形式があり、貧弱なAPIを使用するサードパーティのライブラリがディスク上のデータにアクセスし、データをロードできるファイルへのパスを期待している場合です。
このリンクにはいくつかの良い点があります： http://gamearchitect.net/2008/09/19/good-middleware/
APIがエラーメッセージを生成する場合、メッセージと診断が開発者が問題を解決するのに役立つことを確認してください。
私の期待は、APIの呼び出し元が正しい入力を渡すことです。開発者は（エンドユーザーではなく）APIによって生成されたエラーメッセージのコンシューマーであり、開発者向けのメッセージは開発者が呼び出しプログラムをデバッグするのに役立ちます。
文書化が不適切な場合、APIは不良です。
APIは、十分に文書化され、コーディング標準に従っている場合に適しています。
さて、これらは2つあり、非常にシンプルであり、非常に難しいポイントです。これは、ソフトウェアアーキテクチャの領域に1つをもたらします。システムを構築し、フレームワークが独自のガイドラインに従うのを支援する優れたアーキテクトが必要です。
コードのコメント、APIのよく説明されたマニュアルの記述は必須です。
APIは、それを使用する方法を説明する優れたドキュメントがあれば良いでしょう。しかし、コードがクリーンで良質であり、それ自体が標準に従っている場合、適切なドキュメントがあっても問題ありません。
コーディング構造について少し書きました ここ
最も重要なのは可読性です。つまり、最も多くのプログラマーが、最短の時間でコードが実行していることを理解できる品質を意味します。しかし、どのソフトウェアが読み取り可能で、どれがそうではないかを判断することは、言葉では言い表せないほどの人間の品質、つまりあいまいさです。あなたが言及したポイントは、部分的にそれを結晶化することに成功します。しかし、全体としてはケースバイケースの問題であり続ける必要があり、普遍的なルールを思いつくことは本当に難しいでしょう。