Question

C＃语言规范的附录A涉及文档注释，并指出有两种形式：

单行文档评论：
    /// input-charactersopt
  delimited-doc-comment：
    / ** delimited-comment-textopt * /

有偏好吗？我注意到倾向于选择单行文档评论格式，但我不知道除了人们从美学观点选择之外是否存在技术或实践原因。

我还在书中阅读了＃C; Java开发人员＃34;由琼斯和弗里曼提供以下内容：

代码文档注释前面有三个正斜杠，如下所示：
  /// A single line documentation comment.
  C＃规范还建议使用熟悉的/ **标记来标识多行文档注释。但是，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;
}

所以，重述的问题是哪种形式更可取，是否存在技术或其他原因，在上面的示例，上面的样本或上面的方法2中更喜欢Method1的文档评论样式？

Answer 1

我已经能够收集信息，因为发布此问题确认即使csc /doc:将接受任一格式，单行格式也比多行格式有一些优势：

1）在Visual Studio中，IntelliSense将为您提供信息，说明您在键入时在方法调用表达式中传递的参数，无论您最初是使用///或/ **记录方法。但是，只有在使用///格式时，Visual Studio才会使用预填充来编写文档注释。例如，如果将光标放在Visual Studio中的方法声明上方并按/三次，您将看到为您生成的特定于上下文的模板，如下所示：

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

如果您将光标放在方法上并按/，*，*，则无效。

2）单行格式允许更清晰的文档注释布局，因为每行以相同的缩进开头，可以使用块的所有行，并且每行注释信息都是左对齐的。

3）一般来说，使用单行样式的优点在于单行注释可以自由包含* / token而多行注释不是;如果您在编辑器中将一段注释从一个地方复制/粘贴到另一个地方，它们通常更容易使用。

4）如果考虑csc.exe如何处理相邻的文档块，还有证据表明C＃编译器支持单行格式。考虑这样的声明：

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

当通过csc / doc时：将生成文档，就好像两个块的内容都修改了Main方法一样。此行为不直观，但如果将两个相邻的多行注释块转换为两个相邻的单行注释集，则会变得直观，如下所示：

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

Answer 2

在双（或三）斜线上使用星号时，我从未遇到过任何限制。无论出于何种原因，C＃社区已决定使用双斜杠进行评论。

有趣的是，似乎双斜线评论来自C ++和Java。下面我列出了语言列表，表示语言中的注释：

ALGOL 60 - ; （分号）
汇编语言 - ; （分号）
Ada，mySQL - - （两个破折号）
C ++ / Java - //（两个斜杠）
FORTRAN 90 - ！（感叹号）
Perl，TCL，UNIX Shell，mySQL - ＃（井号）
Visual Basic .NET - '（撇号）

以下是使用双斜杠作为单行和双行注释的工具示例。

Visual Studio 突出显示一段代码并使用组合键Ctrl + K + C，并使用单行双斜线注释掉代码。

Ghost Doc Ghost Doc是一个自动生成方法文档的工具。它使用三次斜杠表示法。我的理解是，在注释中使用XML元素的三重斜杠允许工具NDoc和Sandcastle生成MSDN样式的HTML帮助格式。

Atomineer Pro Atomineer Pro是另一个从方法名称和参数名称生成方法级文档的工具。它默认也使用三斜杠表示法。

MSDN C＃编码标准 C# coding standards表示使用双斜杠，而不是使用块注释。

iDesign C＃编码标准 虽然iDesign不是微软，但我一直觉得他们在C＃社区中有点权威。他们发布了一个C＃编码标准文档，该文档声明双重符号是首选方法。

C＃中的文档注释：更喜欢///或/ **的技术理由是什么

2 个答案: