64

バックグラウンド：

私は大学で「ソフトウェアの制約」という授業を受けています。最初の講義では、優れた API を構築する方法を学びました。

非常に悪い API 関数の良い例はpublic static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds);、C# のソケットです。この関数は、ソケットの 3 つのリストを受け取り、それらを破棄するため、ユーザーはソケットを に供給する前にすべてのソケットのクローンを作成する必要がありますSelect()。サーバーがソケットを待機できる最大時間を設定する int のタイムアウト (マイクロ秒単位) もあります。この制限は +/-35 分です (int であるため)。

質問:

  1. API を「悪い」と定義するにはどうすればよいですか?
  2. API を「良い」と定義するにはどうすればよいですか?

考慮すべき点:

  • 覚えにくい関数名。
  • わかりにくい関数パラメータ。
  • 悪いドキュメンテーション。
  • すべてが相互に関連しているため、1 行のコードを変更する必要がある場合、実際には他の場所で数百行を変更する必要があります。
  • 引数を破棄する関数。
  • 「隠れた」複雑さによるスケーラビリティの悪さ。
  • ユーザー/開発者は、API を使用できるように、API の周りにラッパーを構築する必要があります。
4

13 に答える 13

44

正しく使用するためにドキュメントを読む必要はありません。

素晴らしい API の兆候。

于 2009-01-22T14:12:12.067 に答える
7

優れた API を使用すると、クライアントは必要なほとんどすべてのことを実行できますが、多くの無意味で忙しい作業を行う必要はありません。「マインドレスな多忙な作業」の例としては、データ構造フィールドの初期化、間に実際のカスタム コードがなくても変わらない順序で複数のルーチンを呼び出すことなどがあります。

悪い API の最も確実な兆候は、すべてのクライアントが独自のヘルパー コードで API をラップしたい場合です。少なくとも、API はそのヘルパー コードを提供している必要があります。最も可能性が高いのは、クライアントが毎回独自にロールする、より高いレベルの抽象化を提供するように設計されているはずです。

于 2009-01-22T15:32:08.083 に答える
7

優れた API には、記述内容に近いセマンティック モデルがあります。

たとえば、Excel スプレッドシートを作成および操作するための API にはWorkbook、 、Sheet、およびのようなクラスがあり、 およびCellのようなメソッドがCell.SetValue(text)ありWorkbook.listSheets()ます。

于 2009-01-22T14:12:07.900 に答える
2

There are several other good answers on this already, so I thought I'd just throw in some links I didn't see mentioned.

Articles

  1. "A Little Manual Of API Design" by Jasmin Blanchette of Trolltech
  2. "Defining QT-Style C++ APIs" also Trolltech

Books:

  1. "Effective Java" by Joshua Bloch
  2. "The Practice Of Programming" by Kernighan and Pike
于 2009-06-05T18:14:00.787 に答える
2

優れた API とは、単純なことを単純にし (最も一般的なことを行うための定型文と学習曲線を最小限に抑える)、複雑なことを可能にする (最大の柔軟性、可能な限り少ない仮定) ものです。凡庸な API は、これらのいずれかをうまく実行するものです (非常に単純ですが、本当に基本的なことをしようとしている場合のみ、または非常に強力ですが、非常に急な学習曲線を伴うなど)。ひどい API とは、これらのどちらもうまくいかない API です。

于 2009-06-05T18:01:34.317 に答える
1

API がエラー メッセージを生成する場合は、メッセージと診断が、開発者が問題を解決するのに役立つことを確認してください。

私の期待は、API の呼び出し元が正しい入力を渡すことです。開発者は、(エンド ユーザーではなく) API によって生成されたエラー メッセージの消費者であり、開発者向けのメッセージは、開発者が呼び出しプログラムをデバッグするのに役立ちます。

于 2009-02-05T01:37:02.677 に答える
0

文書化が不十分なAPI は悪いものです。

API は、適切に文書化され、コーディング標準に従っている場合に優れています。

これらは 2 つの非常に単純な点であり、従うのが非常に難しい点でもあります。これは 1 つをソフトウェア アーキテクチャの領域に導きます。システムを構築し、フレームワークが独自のガイドラインに従うのを助ける優れたアーキテクトが必要です。

コードにコメントを付けて、API について十分に説明されたマニュアルを作成することは必須です。

API の使用方法を説明する優れたドキュメントがあれば、その API は優れたものになります。しかし、コードがクリーンで優れていて、それ自体が標準に従っている場合、適切なドキュメントがなくても問題ありません。

ここでコーディング構造について少し書きました

于 2009-01-22T14:01:21.963 に答える
0

最も重要なことは可読性だと思います。つまり、可読性とは、可能な限り短い時間でコードが何をしているのかを、多くのプログラマーが理解できるようにする品質を意味します。しかし、ソフトウェアのどの部分が読み取り可能で、どの部分が読み取り可能でないかを判断することは、言葉では言い表せない人間の性質、つまりあいまいさを持っています。あなたが言及したポイントは、それを結晶化することに部分的に成功しています。しかし、全体としてはケースバイケースであり、普遍的なルールを作ることは非常に困難です。

于 2009-01-22T14:01:37.703 に答える