api - API がオーバーエンジニアリングされるのはいつですか?

Question

私は、単純なことを単純にしない過度に設計された API を扱うことを嫌います。それにもかかわらず、私はオープンソースライブラリの API の設計に取り組んでおり、オーバーエンジニアリングの罠に陥っていると感じ始めています。もちろん、私はひどいことを書いたので、確かに言うことはできません。したがって、それがどのように機能するかは、他の誰よりも私には明らかです。API が過度に設計されている可能性があることを示す、開発者の観点から見た警告サインにはどのようなものがありますか?

score 19 · Accepted Answer

「開発者の観点から見た、API がオーバーエンジニアリングされている可能性がある警告サインは何ですか?」

ユースケースはありません。

単純な「これを行う」シナリオを実行できない場合は、特定のユースケースを念頭に置いて有用な API を設計していません。

あなたのドキュメントはそれらのユースケースでなければなりません。

ユースケースに直接対応していない機能は、おそらくオーバーエンジニアリングです。

score 11 · Accepted Answer

Joshua Bloch による Google Tech Talk How To Design A Good API and Why it Mattersをチェックしてください。彼はこのようなことをたくさんカバーしています。

score 5 · Accepted Answer

私が非常に便利だと思ったトリックの1つは、過去に私を助けてくれました。コードを書く前、コーディング中、コーディング後にドキュメントを書くことです。

他の人が使用するAPIを設計するとき、私は通常、コードを書く前に設計を文書化します。私が設計を過剰に設計していた場合、設計仕様は通常、矛盾とナンセンスに満ちています。

コーディング中、私は通常、クラス定義と関数本体をスタブし、それらのdoxygenコメントを書き始めます。コメントでは、ユースケース、サンプルコード、およびインターフェイスの前提条件について説明します。このフェーズでは、実際のコードを記述しすぎる前に、クラスインターフェイスは通常何度も再設計されます。サンプルコードを書くのが難しく、インターフェースを説明するのに苦労しているとき、私はエンジニアリングをやり過ぎていたことを知っています。APIの使用方法を人々に説明しようとすると、多くの悪い設計のアイデアが明らかになり、排除されます。

コーディング後、コメント内のサンプルコードを、単体テストからコピーされた実際のコンパイルおよびテスト済みコードに置き換え、インターフェイスの動作をさらに文書化します。オーバーエンジニアリングのもう1つの兆候は、可動部品が多すぎて同じことを行う方法が多すぎて、単体テストが指数関数的に増加するために、単体テストがインターフェイスの変更に対応できない場合です。

score 4 · Accepted Answer

一般的なAPI呼び出しのスタックトレースで、画面をスクロールして全体を表示する必要がある場合。

score 2 · Accepted Answer

ドキュメントと例を確認すると、信頼できるユースケースへのアプリケーションを議論する言葉遣いの割合と比較して、API 自体に関連して議論する言葉遣いの割合が比較されます。

score 2 · Accepted Answer

S.Lottが言ったように、ユースケース。それらは、API が何を行うべきかを正確に決定します。非常に明確で具体的な目標 (機能的に一貫性がある) を達成するように API を設計すると、最終的に、使いやすく理解しやすい API または API 内のコンポーネントになる可能性が高くなります。

API の設計は、ユーザーインターフェイスの設計に似ている必要があります。KISS の原則やカイゼンなど、UI のほとんどすべての概念を API に組み込むことができます。

私はそれらの UI コンセプトにリンクしたいと思いますが、私は新しいユーザーなので、1 つ以上のハイパーリンクを投稿することはできません。良い例: StackOverflow、投稿する前にお知らせください ;)。

score 1 · Accepted Answer

多くの関数を備えた大規模なAPIがある場合、心配し始めます。これらの関数を詳しく調べると、より単純な操作の構成であることがわかります。プリミティブに対する構成メカニズムの比率が高いAPIは、通常、優れた設計です。

（API設計は言語設計と非常に似ています。ここでは、基本的にスキームの哲学を支持しています。APIにルーチンを追加するのではなく、APIを単純化し、追加のルーチンを不要にする構成メカニズムを含めます。）

score 1 · Accepted Answer

自問すべき 2 つの (関連する) 質問がすぐに思い浮かびます。

複数の方法で実行できることはありますか?
API の残りの部分に関して表現できる API のメソッド/プロパティはありますか?

答えるのはより難しく、それ自体がオーバーエンジニアリングの兆候ではありませんが、API がまだ可能な限り単純ではない兆候であることは間違いありません。

導入した以上のものを削除できるようにするために導入できる他のメソッド/プロパティはありますか (他の 2 つの質問に基づいて)

score 0 · Accepted Answer

API を使用する場合: (1) 基礎となるテクノロジを使用する場合よりも、より鈍く、より複雑で、効率が低く、予測可能性が低く、かつ (2) 安全性、スケーラビリティ、またはクロスプラットフォームの自由度に関して大きな利点はありません。

score 0 · Accepted Answer

私の経験では、API の完成を待って、プロジェクト全体が何か月も保留になっている時期を知ることができます。

api - API がオーバーエンジニアリングされるのはいつですか?

11 に答える 11

Related

Reference