4

C# のスタイル ガイドのようなものを作成する必要があり、現在、どのコメントが意味を持ち、どのコメントが意味をなさないかを把握する必要があります。私は、Robert C. Martin の「Clean Code」という本や、C# に関する他の本 (O'Reillys c# 4.0 など) などで多くの作業を行っています ... しかし、名前空間のコメントについての言葉が見つかりません ...ええと...正直に言うと、名前空間にコメントする正当な理由を見つけることができません。もう 1 つは、Visual Studio に付属の XML ドキュメントを使用したいのですが、名前空間の既定の実装がありません。

私に正当な理由がありますか？

4

2 に答える 2

3

System.Data 名前空間に関するこの MSDN ページをご覧ください。

これは、この名前空間のクラスに期待されることの概要を提供し、それらがどのように連携するかを示しています。

そのため、貴重なドキュメントを名前空間に追加する正当な理由があるかもしれません。

どのタイプを期待し、追加し、どのように使用するかを知ることは非常に価値があります。この情報を他の場所で収集するのは難しい場合があるためです。

于 2012-12-18T08:09:49.463 に答える
2

名前空間のドキュメントでカバーできる (そして、必要に応じて、IMHO がすべき) 2 つの側面があります。

  • 名前空間には何がありますか? : 名前空間は任意のグループ化ではありません。通常、1 つの名前空間内の型には共通のテーマがあります。この分類は、名前空間のコメントで説明できます。単一の名前空間識別子が正確で明確であることはめったにないためです。特に、一緒に動作することを意図した特定のタイプのセットが名前空間に含まれている場合、名前空間のコメントは、タイプを一緒に使用する方法を説明する場所です。(または、最初にインスタンス化する型、または名前空間で最も重要な型を通知することもできます。)
  • 名前空間には何を配置できますか? : 名前空間がサード パーティによって拡張されることを意図している場合 (より多くの型を追加する)、コメントには、名前空間が適している可能性のある将来の型と、名前空間に入れるべきではない型についても説明する必要があります。たとえば、名前空間YourCompany.Textが文字列処理に関連する型を対象としていることを指摘したり、名前空間内の何かの非常に特定のプラグイン型のみを対象としていることを指摘したりYourCompanyできます。その情報は、ネームスペース名だけから推測することはできません。

さらに、コメントをある種のマニュアル (Sandcastle や NDoc など) にフォーマットするドキュメント ジェネレーターを使用する場合、名前空間ページ (名前空間内のすべての型を一覧表示するページ) は、名前空間ドキュメント コメントを追加として受け取ります。情報。単一の名前空間名と (場合によっては非常に長い) 型のリストではなく、簡単な概要を取得することは、優れた名前空間ベースのドキュメントにとって重要であると見なすことができます。

于 2012-12-18T08:03:09.867 に答える