APIは大きな力であり、大きな責任です。 優れたAPIには感謝するユーザーがいます。 悪い人を支援することは悪夢に変わります。
公開API-すずめ、公開しない-削除しません。 すべてを正しく実行しようとする試みは1つだけなので、試してください。
APIは簡単に使用できるはずですが、誤って使用することは困難です。 そのようなAPIを使用して何かを簡単にするのは簡単です。 難しいことは可能です。 何か間違ったことをすることは不可能か、少なくとも難しいはずです。
APIは自身を記述する必要があります。 このようなAPIでコードを学習しても、コメントを読みたいという欲求は生じません。 一般に、コメントはほとんど必要ありません。
APIを開発する前に、ある程度の健全な懐疑心を持って要件を組み立てます。 一般的なタスクを実現し、解決します。
APIの使用パターンとして要件を設計します。 設計プロセス中に確認してください。
最初のドラフトでは、APIは簡潔で、通常は署名と1行の説明を含む1ページにする必要があります 。 すべてが正しくない場合、やり直しが簡単になります。
詳細な定義の前であっても、APIを実装する前に使用パターンをエンコードします 。 これにより、基本的に実行不可能なAPIに時間を費やすことはありません。
APIの進化に合わせて、使用パターンのコードを変更します。 これにより、不快な驚きがなくなります。 次に、テンプレートを例、ドキュメント、およびテストで使用できます。
例のコードは例示的なものである必要があります。 ユーザーはそれをプログラムにコピーします。 わずかな間違いは約100倍です。
すべての人を満足させることはできませんが、すべての人を平等に満足させるよう努めてください。 ほとんどのAPIは作成者のニーズに合わせて調整されているため、柔軟性が奪われています。
APIの設計におけるあなた自身の間違いに備えてください。 APIを使用するためのすべてのシナリオ、環境と対話する副作用などを熟知していると信じるのは簡単です。
APIを開発するとき、現場の人は戦士ではありません。 できるだけ多くの同僚にAPIを見せ、批判する。 彼らはあなたの間違いに気付くかもしれません。
名前は重要です。 明快さと対称性に努めます。 一貫してください。 各APIは小さな言語であり、ユーザーはそのAPIの読み書きを学習します。 良いAPIコードは自然なテキストのようなものです。
良い名前を思い付くのは不可能です-設計に戻りましょう。 APIをシャベルすることを恐れないでください。 名前が一対一になっている場合、あなたは正しい軌道に乗っています。
疑い-削除。 おそらく、APIを開発するための主なルールです。 機能ブロック、モジュール、クラス、関数、メソッド、パラメーターのすべてに関係します。 APIの個々の部分はできるだけ小さくする必要がありますが、それより小さくする必要はありません。 何かを追加する時間は常にありますが、削除することはできません。 まず、クラスやメソッドではなく、意味の数を減らします。
実装の詳細がAPIに浸透しないようにしてください。 これはユーザーを混乱させ、API開発を困難にします。 実装の詳細があることを理解することは必ずしも容易ではありません： 過度の詳細に注意してください。 たとえば、APIでハッシュ関数アルゴリズムを指定しないでください。
ボラティリティを減らします。 不変オブジェクトはシンプルで安全です。
ドキュメントが重要です。 ドキュメントなしでは、誰も優れたAPIを使用しません。 すべてのパブリックエンティティ（すべてのクラス、すべての関数、すべての引数、すべてのフィールド）を記述します。
APIソリューションのパフォーマンスへの影響を念頭に置いてください。ただし、APIの品質を超えないようにしてください。 幸いなことに、良いAPIは通常、パフォーマンスの高い友人です。
チャーターで奇妙な修道院に行かないでください。 APIは、慣例に従って、言語とプラットフォームに有機的に適合する必要があります。 悪いアイデアは、あるプラットフォームから別のプラットフォームにAPIを変更せずに移植することです。
可用性を削減します。 あなたはそれを疑います-プライベートにします。 これにより、APIが簡素化され、接続性が低下します。
サブクラスの各インスタンスがスーパークラスのインスタンスであると曲がることなく言うことができる場合にのみ、継承を使用します。 パブリッククラスは、実装を再利用するためだけに継承できません。
継承の可能性を考えて文書化するか、それを禁止します。 ドキュメントで、クラスメソッドが相互に呼び出す方法とタイミングを説明します。 これなしでは安全な継承はできません。
ライブラリに対してユーザーに何もさせないでください。 確実な記号は、APIを使用するときに繰り返されるコードです。 これは退屈で、エラーに満ちています。
最も驚きの原則に従ってください。 関数は、その名前と署名について最も期待されることを行う必要があります。
使用中のエラーができるだけ早くポップアップするように努めてください。 すべてのベスト-コンパイル段階で。 実行時-できれば最初の誤った呼び出しで。
テキストとして利用可能なすべてのものへのプログラムによるアクセスを提供します。 ユーザーに行を解析する運命の人は非人道的です。 さらに悪いことに、テキスト形式は実際にはAPIの一部になります。 例：スタックトレースを印刷できる場合、フレームへのリンクのリストを取得できるはずです。
メソッド/関数をオーバーロードするには注意が必要です。 それらの効果が異なる場合は、異なる名前を付けることをお勧めします。
最適なタイプを使用してください。 たとえば、数字や文字列ではなく、特殊なタイプとしてIPアドレスを受け入れて渡します。
関数で引数の順序を1つ保持します。 そうしないと、ユーザーはすべてを混同します。
特に同じタイプの複数のピースが連続する場合は、引数の長いリストを避けてください 。
メソッドは、特別な処理を必要とする値を返すべきではありません。 ユーザーはチェックを忘れます。 たとえば、
null
ではなく空の配列またはリストを返し
null
。
例外は例外的な状況のみです。 例外処理は、クライアントプログラムのコアロジックの一部であってはなりません。 これは見苦しく、エラーが多く、多くの場合パフォーマンスを上回ります。
ユーザーがエラーを有意義に処理できない可能性がある場合は、未チェックの例外をスローします。
APIの作成は芸術であり、科学ではありません。 美しさを考え、直感を信じてください。 盲目的にこれらの規則に従わないでください。しかし、たまにしか正当な理由でそれらに違反しないでください。
プレゼンテーションとビデオ ：同じことですが、言葉が少し異なり、Javaの例もあります。