0

顧客の開発者がライブラリとしてリリースされるプロプライエタリCモジュールを使用できるようにするAPIを作成する必要があります（ソースではなく、考えてみてください）.lib。.so

ベストプラクティスに従い、説明、例、警告などを含むコメントを提供して、ヘッダーをできるだけ開発者にとって使いやすいものにしたいと思います（そうする必要はありません）。

ビジネス、技術、および常識的な観点から、他に何を考慮する必要がありますか？

ありがとう！

4

6 に答える 6

4

他の場所で定義されている可能性のあるシンボルを (再) 定義しないようにしてください。標準的な名前だけを意味するわけではありません。パブリック ヘッダーで宣言/定義されているすべてのシンボルの前に特定の文字列を付けて、他の人が使用する可能性のある名前を避けてください。

これは、「プロフェッショナルな」公開ヘッダーでこのような狂気を目にした後に言います。

typedef unsigned short uchar;
于 2008-11-11T21:53:08.183 に答える
4

1 つのオプションは、(たとえば) Doxygen を使用してヘッダーから API ドキュメントを生成することです。明らかに、コードと一緒にドキュメントを出荷します。

これにより、次の 2 つの利点が得られます。

1) 何かが「ドキュメント内」にあるべきか、単に「ヘッダーのコメント」にあるべきかについてあまり心配する必要はありません。一方を変更するのは、他方を変更するのと同じくらい簡単だからです。したがって、すべてがドキュメントに記載されています。

2) ユーザーは、最初からヘッダー ファイルを読みに行く可能性が低くなります。これは、関心のあるすべてがドキュメントに含まれていることを合理的に確信できるからです。しかし、彼らが頑固な「私はドキュメントを信用していない、私はコードを読んでいる」タイプであっても、あなたが見たいものはすべて見ています.

自動生成された API ドキュメントの欠点は、検索が困難になる可能性があることです。したがって、IMO では、本当に優れた「入門」ドキュメントを作成するためにさらに努力する価値があります。これは、好みに応じて、生成された API ドキュメントの一部である場合とそうでない場合があります。小さな API の場合、アルファベット順やソース順ではなく「論理的」なすべての関数のリストだけで、関数が何をするのかではなく何のためにあるのかに応じて記述されているだけで、API ドキュメントに簡単にアクセスできます。「論理的」とは、クライアントが呼び出す順序で、一般的に使用される関数を最初にリストすることを意味し、「同じ種類のことを行う」(ソケットの send および sendTo など) 代替をグループ化します。次に、あまり使用されない関数をリストします。

ショーストッパーになる可能性があるこのアプローチの主な問題の 1 つは、組織によってはドキュメント チームがあり、ヘッダーを編集できない場合があることです。最善のシナリオは、あなたが行ったことを彼らがコピー編集し、あなたが変更を加えてフィードバックすることです。最悪のシナリオは、「顧客向けのドキュメントを作成するのはドキュメント チームだけであり、ドキュメントは標準形式でなければならず、Doxygen にその形式で出力させることができない」ため、アイデア全体が停止することです。

「他に何を考慮すべきか」については、ベストプラクティスに従うとすでに述べているので、多くを追加するのは難しいです:-)

于 2008-11-10T00:56:22.107 に答える
4

他の人がドキュメンテーションの問題に言及したので、私はそれらから離れます :-P. まず、適切なインクルード ガードがあることを確認します。個人的に私は好きな傾向があります：

FILENAME_20081110_H_、基本的にすべて大文字のファイル名、次に完全な日付。これは、ツリーに同じ名前の別のヘッダーがある場合でも、十分に一意であることを確認するのに役立ちます。(たとえば、2 つの異なる lib ディレクトリから含まれる 2 つの config.h に、CONFIG_H_またはそのようなものを使用するガードがあり、競合が発生していると想像できます。一意である可能性が高い限り、何を選択しても問題ありません。

また、このヘッダーが C++ プロジェクトで使用される可能性がある場合は、ヘッダーを次のようにブロックでラップしてください。

#ifdef __cplusplus
extern "C" {
#endif

/* your stuff */

#ifdef __cplusplus
}
#endif

これにより、名前マングリングの問題による頭痛が解消され、ヘッダーをこれらで外部的にラップする必要がなくなります。

于 2008-11-10T16:37:35.090 に答える
3

ヘッダー ファイル自体は、クリーンで整頓されていて、おそらく最小限に近いものである必要があります。ドキュメントが見つかる場所を指している必要があります。おそらく完全な例を含めるべきではありません (それを行う私自身のヘッダーのいくつかにもかかわらず)。これには、著作権とライセンスに関する基本情報と、作者の詳細が含まれている必要があります。エンド ユーザーが必要とするものだけを含める必要があります。開発者だけが必要とするものは何もありません。自己完結型である必要があります。それを機能させるために必要な他のヘッダーを含める必要があります (そのため、ユーザーは ' #include "your-header.h"' を書くことができ、それが最初または唯一のヘッダーであっても、コードはきれいにコンパイルされます)。

追加: ヘッダーには、いくつかの基本的なバージョン情報も含める必要があります (ファイルのリビジョン番号と変更日、および/または製品リリースのバージョン番号とリリース日)。これは、ソフトウェアの 2 つのリリースを検討している人々に役立ちます。また、成功したソフトウェアは複数回リリースされています。

追加: Adam は、「開発者だけが必要とするものは何もない」と拡張するように私に依頼しました。つまり、たとえば、内部関数が何らかの構造型を使用している場合でも、その構造型を使用する外部インターフェイスがない場合は、パブリック ヘッダーにその構造型の定義を含めないでください。配布されていない (または完全なソースと共にのみ配布されている) プライベート ヘッダーにある必要があります。公開ヘッダーを汚染するべきではありません。「ほんの少しの無駄なスペースだ」と言いたくなりますが、それは正確ですが、誰もが少しのスペースと時間を無駄にすると、全体の無駄が高くつく可能性があります。

パブリック ヘッダーに関する重要な点は、ライブラリ (関数のセット) のユーザーが必要とするすべてのものを含める必要があり、必要のないものは何も含めないことです。

于 2008-11-10T00:44:33.893 に答える
2

実際に別のドキュメントを作成することを検討してください。man / infoページは、APIドキュメントがどのようなものであるかについての良い例を提供すると思います。

于 2008-11-10T00:35:12.397 に答える
1

出荷されるものに加えて、ドキュメントをオンラインに置くことを検討し、URL をヘッダーに入れます。これにより、メンテナンス プログラマーは数年後、元のドキュメントを紛失した場合でもドキュメントにアクセスできるようになります。

于 2008-11-10T16:30:57.197 に答える