C++ でパブリック ヘッダー ファイルを作成するときのベスト プラクティスは何だと思いますか?
ヘッダー ファイルには、ドキュメントをまったく含めないか、簡潔にするか、大量のドキュメントを含める必要がありますか? ドキュメントがほとんどない (いくつかの外部ドキュメントに依存している) ものから、不変条件、有効なパラメーター、戻り値などの大規模な仕様まで、すべてを見てきました。一方、非常に簡潔なドキュメントを含むヘッダー ファイルは、多くの場合、1 ページまたは 2 ページのテキストで完全なインターフェイスを示し、クラスで何ができるかについてのより良い概要を示します。
簡単なドキュメントや大規模なドキュメントのようなものを使用するとします。戻り値、パラメーターなどを文書化する javadoc に似たものが必要です。C++ での最適な規則は何ですか? 私が覚えている限りでは、doxygen は Java doc スタイルのドキュメントでうまく機能しますが、javadoc スタイルのドキュメントを参照する前に知っておくべき他の規則やツールはありますか?
通常、インターフェイスのドキュメント (パラメーター、戻り値、関数の動作) をインターフェイス ファイル ( .h ) に、実装のドキュメント (関数の動作方法) を実装ファイル (.c、.cpp、 .m)。
宣言の直前にクラスの概要を書くので、読者はすぐに基本的な情報を得ることができます。
私が使用するツールは Doxygen です。
ヘッダーファイル自体にいくつかのドキュメントがあることは間違いありません。個別のドキュメントではなく、コードの横に情報があるため、デバッグが大幅に改善されます。経験則として、コードの横に API (戻り値、引数、状態の変更など) を記述し、ハイレベルなアーキテクチャの概要を別のドキュメントに記述します (すべてがどのようにまとめられているかをより広く理解できるようにするためです。通常、一度に複数のクラスを参照するため、これをコードと一緒に配置するのは困難です)。
私の経験からすると、Doxygenは問題ありません。
単独で使用できるように、コードに十分な量を入れてください。私が参加したほぼすべてのプロジェクトで、ドキュメントが別のものだったり、時代遅れになったり、完了していなかったりしました。一部には、別のドキュメントである場合、別のタスクになることもありました。一部には、経営陣がそれをタスクとして許可していなかったためです。予算編成で。私の経験では、フローの一部としてインラインで文書化する方がはるかにうまく機能します。
ほとんどの編集者がブロックであると認識する形式でドキュメンテーションを書きます。C++ の場合、これは // ではなく /* のようです。そうすれば、折りたたんで宣言だけを見ることができます。
gtk-docに興味があるかもしれません。「セットアップと使用が少し面倒」かもしれませんが、ソース コードから次のような素敵な API ドキュメントを取得できます。