8

C# 语言规范的附录 A 处理文档注释，它指出有两种形式：

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

有偏好吗？我注意到倾向于使用单行文档注释格式，但我不知道除了人们从美学角度进行选择之外是否还有技术或实际原因。

我还在 Jones 和 Freeman 的“C# for Java Developers”一书中阅读了以下内容：

代码文档注释前面有三个正斜杠，如下所示：
/// 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;
}

因此，重申一下，问题是哪种形式更可取，是否有技术或其他原因更喜欢上面示例中的 Method1 或上面示例中的 Method2 的文档注释样式？

4

2 回答 2

6

自从发布此问题以来，我能够收集到的信息证实，即使csc /doc:将接受任何一种格式，单行格式也比多行格式具有一些优势：

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

    /// <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 方法一样。这种行为并不直观，但如果将两个相邻的多行注释块转换为两个相邻的单行注释集，就会变得直观，如下所示：

    /// <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 - --（两个破折号）
  4. C++/Java - //（两个斜杠）
  5. FORTRAN 90 - ！（感叹号）
  6. Perl、TCL、UNIX Shell、mySQL - #（井号）
  7. Visual Basic .NET - '（撇号）

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

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

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

Atomineer Pro Atomineer Pro是另一个工具，它可以根据方法名称和参数名称生成方法级别的文档。默认情况下，它还使用三斜杠表示法。

MSDN C# 编码标准C# 编码标准说要使用双斜杠， 而不是使用块注释。

iDesign C# 编码标准 虽然iDesign不是 Microsoft，但我一直觉得它们在 C# 社区中有点权威。他们发布了一份 C# 编码标准文档，其中指出双符号是首选方法。

于 2013-09-04T06:12:56.170 回答