回答:
Joshua Blosh（Google）が「優れたAPIを設計する方法とそれが重要である理由」にあるベストプラクティスに従います。PDF版はここにあります。
彼によると、優れたAPIの特徴は次のとおりです。
習得が容易
であってもドキュメントなしで、使いやすいを
誤用するのは難しい
、それが使用するコードの読み取りと保守が容易に
要件を満たすために十分に強力で
簡単に拡張するための
聴衆に適切に
私は以下が欲しい：
明確に定義された名前空間。Cが第一言語であるため、これに一致するマクロも必要です。その領域での競合の解決は失敗です。
何かを割り当てる場合は、解放する必要があるという明白な手掛かりをいくつか教えてください。これは私の次のポイント、つまりドキュメントです。
ライブラリを文書化します。Doxygenのようなツールはシンプルで移植性があり、生成して参照できるものを私に与えないという言い訳はありません。
パブリックヘッダーに不透明型をドキュメント化します。私はとにかくそれらを見つけるつもりです、なぜ私がそれらをいじるのを望まないのか、そして私がそうした場合に何が起こり得るのか教えてください。実際にパッチが必要な場合、私はあなたが何を考えていたかを知る必要があります。
落下して実行しないでください。私は本当にのようなコメントに感謝「、これについて私に連絡しないでください。私はそれを維持するつもりはありません。これは、多分それはあなたの問題を解決します。私は気にしない、私は更新するつもりはない、私の当面の問題を解決しましたこれで、自由にフォークできます。」どれだけの時間を節約できたかは言えません。
既存のコードにメモリリークやエラーが追加されることはありません。自分のコードにデータをプッシュする前にテストを行わない場合、なぜそれを自分のコードにプッシュするように誘惑するのですか？
それが実際にライブラリである場合は、寛容なライセンスを使用し、一貫性を保ってください。あなたはそれからより多くのお金を稼ぐべきであると今から3ヶ月を決定しないでください。これは、何かを出荷する前の夜に迷惑をかけるだけではなく、ライセンスが変更されたため、一連のライブラリコードを書き直す必要があることを認識しています。それはまさに、MITライセンスの下であなたのコンテンツを再実装するのに十分イライラさせるようなものです。
コーディングスタイルに一貫性があるようにしてください。他の人がコードを読んで、期待どおりに動作しない場合に実際に何が行われているかを理解する必要があります。
110列を超えて使用しないでください。コードを適切に編集する必要があり、80x25のディスプレイしか表示されない場合があります。タブを使用して物事をより「上品」に見せる場合、解決すべき他の問題があります。
インタプリタ言語を扱っていない場合は、少なくともポートを検討するようにしてください。それでも、少なくともポートを検討するようにしてください。
テストしてください。私はあなたがそれらを持っていることを願っています、そうでなければ私はそれらを提案するかもしれません、そして私は実際にコールグラフに基づいてそれらを書くのを助けるかもしれません。私がそのすべての問題を経験した場合は、親切にそれらを使用してください。それ以外の場合は、「私のために働く」パッチを入手します。:)
API、期間を壊さないでください。私はあなたがすべてを間違えてしまったことに気づくかもしれませんが、あなたにリンクしているものが単純な更新で壊れないことを確認してください。それは、図書館の世界へようこそ、いくつかのくだらないものや汚物を意味するかもしれません。
あなたの仕事や他の人の仕事を複製しないように、ロードマップを教えてください。
この投稿を編集してさらに追加する予定です。
getcwd適切に使用するには、十分に大きくなるまでバッファを拡張するループを作成する必要があります（例を参照）。
APIのソフト機能についてもっと心配しています。あれは：
それらがどのように適用されるか、またはどのように実装されるかについての本を正すことはできますが、APIのユーザーが効果的に使用する方法に頭を抱えられない限り、使用は制限されます。エレガンスがオンテートを意味しないのと同じように、シンプルさは単純さを意味しません。それは単に、それが仕事にぴったりであることを意味します。誰かがAPIの使用方法について考える必要が少なくなればなるほど、APIを使用できるようになります。
これらの外観は、APIの言語、目的、対象ユーザーによって異なります。最後の基準は、最小の驚きの原則に要約されます。あなたがそれらを期待していなかったところでエラーはありません。APIの妥当な解釈があれば、必要な結果が得られます。
これは、他のすべての設計哲学をほぼ要約しています。ライブラリが複雑なことのみを可能にする場合、使用例の最も簡単な80％を解決しようとする人々は、6つの異なるクラスを使用してライブラリの「Hello世界"。
ライブラリが単純なものを単純にするだけの場合、人々は彼らがちょっとした道を少し外れた要件を持っていたからといって彼らがコードを書き直す必要があると分かったとき、人々はすぐにイライラするでしょう。
これを実現する最良の方法は次のとおりです。
受け入れることを自由にしてください。動的言語でプログラミングしている場合は、ダックタイピングを使用して効果を最大限に引き出します。C ++またはDでプログラミングしている場合は、可能な限りテンプレートを使用してください。ある程度普遍的な構造的インターフェースを満たすものはすべて受け入れます。データをある形式から別の形式に変換する多忙な作業をユーザーに強制しないでください。
ライブラリに高レベルの便利な機能を構築しますが、それを低レベルの機能の上に透過的な方法で構築し、低レベルの機能がそれを必要とする人々のためにあることを確認してください。
柔軟性や効率を制限する可能性がある場合でも、デフォルトでは最小の驚きの原則に従います。必要に応じて、最適化または柔軟性の向上を可能にするためにその驚くべきことを強調する、より詳細な名前の2番目の関数を追加します。
カプセル化は便利ですが、それについて無口ではありません。異常で予期しない要件を持つ人々は、仕事を完了するために、抽象化の1つの下に入る必要がある場合があります。一方、一見無害な構成を使用している場合、誤って足を自分で撃つことは困難です。どれだけ厳密にロックダウンするかを決定するときは、このことを覚えておいてください。
ドキュメントでは、例を多用します。これは、ユーザーに一般的な使用例を説明するためと、最も一般的なケースが十分に合理化されているかどうかを考えるように強制するための両方に役立ちます。
可能な限りすべてに適切なデフォルトを設定してください。ただし、それらのデフォルトが単なるデフォルトであり、それらをオーバーライドする方法が明確であることを確認してください。
それで全部です。例として、WindowsとUNIXのパイプのメカニズムを比較してください。1つは、多くのマクロ/定数値の1つを持つことができる、あいまいで不要な、またはめったに使用されない引数を備えた一連の特殊なAPI関数を提供します。UNIXは基本的に、既存のオープン/読み取り/書き込み/クローズインターフェースと、socketpair（）やpipe（）などの特定のケースに対応するいくつかの非常に単純なメソッドを再利用します。UNIXでパイプを使用するために、習得すべき新しいことはほとんどありません。これと比較してください。
（公平を期するために、Microsoftは当初、IBMのOS / 2からそのインターフェースを「借りた」だけでした。）