8

C# 言語仕様の付録 A では、ドキュメント コメントを扱っており、次の 2 つの形式があると記載されています。

single-line-doc-comment:
/// input-charactersopt
delimited-doc-comment:
/** delimited-comment-textopt */

好みはありますか？単一行のドキュメント コメント形式を好む傾向があることに気付きましたが、人々が美的観点から選択する以外に、技術的または実用的な理由があるかどうかはわかりません。

また、Jones と Freeman による「C# for Java Developers」という本を読んだことがあります。

次に示すように、コード ドキュメント コメントの前には 3 つのスラッシュが付き
/// A single line documentation comment.
ます。ただし、C# コンパイラのバージョン 7.00 はこの構文をサポートしていません。

csc の最新バージョンが複数行の構文で機能しないことを確認できませんでした。私が知る限り、この構文は問題なく機能します。

**edit**サンプルを見せてほしいと言う人もいました。サンプルは次のとおりです。

/// <summary>
/// Performs a Method1 calculation on two strings
/// </summary>
/// <param name="arg1">The first string</param>
/// <param name="arg2">The second string</param>
/// <returns>The number 3</returns>
public static int Method1(String arg1, String arg2)
{
    return 3;
}
/**
 * <summary>
 * Performs a Method2 calculation on two strings
 * </summary>
 * <param name="arg1">The first string</param>
 * <param name="arg2">The second string</param>
 * <returns>The number 3</returns>
 */ 
public static int Method2(String arg1, String arg2)
{
    return 3;
}

上記のサンプルの Method1 または上記のサンプルの Method2 のドキュメント コメント スタイルを好む技術的またはその他の理由はありますか?

4

2 に答える 2

6

この質問を投稿してから収集できた情報はcsc /doc:、どちらの形式も受け入れますが、単一行形式には複数行形式よりもいくつかの利点があることを確認しています。

1) Visual Studio では、IntelliSense は、最初に /// または /** でメソッドを文書化したかどうかに関係なく、入力時にメソッド呼び出し式で渡す引数を明確にする情報を提供します。ただし、Visual Studio は、/// 形式を使用する場合にのみ、事前入力を使用してドキュメント コメントを記述することをサポートします。たとえば、Visual Studio のメソッド宣言の上にカーソルを置いて/3 回押すと、次のようにコンテキスト固有のテンプレートが生成されます。

    /// <summary>
    /// 
    /// </summary>
    /// <param name="arg1"></param>
    /// <param name="arg2"></param>
    /// <returns></returns>

/メソッドにカーソルを合わせて , , を押すと*、これは機能しません*。

2) 単一行形式では、各行が同じインデントで始まり、ブロックのすべての行を使用でき、コメント情報の各行が左揃えになるため、ドキュメンテーション コメントのよりクリーンなレイアウトが可能になります。

3) 一般に、単一行コメントには */ トークンを自由に含めることができますが、複数行コメントには含めないという点で、単一行スタイルを使用する利点があります。また、エディター内でコメントの一部をある場所から別の場所にコピー/貼り付けする場合は、一般的に作業が簡単になります。

4) csc.exe が隣接するドキュメント ブロックをどのように処理するかを考慮すると、C# コンパイラが単一行形式を好むという証拠もあります。次のような宣言を検討してください。

   /**
     * <thiscutetag>some info</thiscutetag>
     */
    /**
     * <theothercutetag>more info</theothercutetag>
     */
    public static void Main() { }

csc /doc を通過する場合: ドキュメントは、両方のブロックの内容が Main メソッドを変更したかのように生成されます。この動作は直感的ではありませんが、次のように、2 つの隣接する複数行コメント ブロックを 2 つの隣接する 1 行コメントのセットに変換すると、直感的になります。

    /// <thiscutetag>some info</thiscutetag>
    /// <theothercutetag>more info</theothercutetag>
    public static void Main() { }
于 2013-09-04T05:26:25.113 に答える
0

二重 (または三重) のスラッシュにアスタリスクを使用する場合、制限に遭遇したことはありません。何らかの理由で、C# コミュニティはコメントに二重スラッシュを使用することにしました。

興味深いことに、ダブル スラッシュ コメントは C++ と Java から出てきたようです。以下に、言語のリストとその言語のコメントを示します。

  1. アルゴル 60 - ; （セミコロン）
  2. アセンブリ言語 - ; （セミコロン）
  3. Ada、mySQL - -- (2 つのダッシュ)
  4. C++/Java - // (2 つのスラッシュ)
  5. FORTRAN 90 - ! （エクスクラメーション・マーク）
  6. Perl、TCL、UNIX Shell、mySQL - # (ハッシュ記号)
  7. Visual Basic .NET - ' (アポストロフィ)

以下は、ダブル スラッシュを 1 行および 2 行のコメントとして使用するツールの例です。

Visual Studio コードのブロックを強調表示し、キーの組み合わせ Ctrl + K + C を使用すると、コードは 1 行のダブル スラッシュを使用してコメント アウトされます。

Ghost Doc Ghost Docは、メソッドのドキュメントを自動生成するツールです。トリプル スラッシュ表記を使用します。コメントで XML 要素を使用したトリプル スラッシュにより、NDocやSandcastleなどのツールがMSDN スタイルの HTML ヘルプ形式を生成できるようになると私は理解しています。

Atomineer Pro Atomineer Proは、メソッド名とパラメーター名からメソッド レベルのドキュメントを生成する別のツールです。また、デフォルトでトリプル スラッシュ表記を使用しました。

MSDN C# コーディング標準C# コーディング標準で は、ダブル スラッシュを使用し、ブロック コメントを使用しないように規定されています。

iDesign C# コーディング標準iDesignは Microsoft ではありませんが、C# コミュニティ では iDesignが多少の権威であると常に感じていました。彼らは、二重表記法が推奨される方法であると述べている C# コーディング標準ドキュメントを公開しています。

于 2013-09-04T06:12:56.170 に答える