2.9 使用注释

本节的内容是给代码添加注释，该主题表面看来十分简单，但实际可能很复杂。注释有助于阅读代码的其他开发人员理解代码，而且可以用来为其他开发人员生成代码的文档。

2.9.1 源文件中的内部注释

本章开头提到过，C#使用传统的C风格注释方式：单行注释使用// ...，多行注释使用/* ... */：

        // This is a single-line comment
        /* This comment
          spans multiple lines. */

单行注释中的任何内容，即从//开始一直到行尾的内容都会被编译器忽略。多行注释中“/*”和“*/”之间的所有内容也会被忽略。显然不能在多行注释中包含“*/”组合，因为这会被当成注释的结尾。

实际上，可以把多行注释放在一行代码中：

        WriteLine(/* Here's a comment! */ "This will compile.");

像这样的内联注释在使用时应小心，因为它们会使代码难以理解。但这样的注释在调试时是非常有用的，例如，在运行代码时要临时使用另一个值：

        DoSomething(Width, /*Height*/ 100);

当然，字符串字面值中的注释字符会按照一般的字符来处理：

        string s = "/* This is just a normal string .*/";

2.9.2 XML文档

如前所述，除了C风格的注释外，C#还有一个非常出色的功能(本章将讨论这一功能)：根据特定的注释自动创建XML格式的文档说明。这些注释都是单行注释，但都以3条斜杠(///)开头，而不是通常的两条斜杠。在这些注释中，可以把包含类型和类型成员的文档说明的XML标记放在代码中。

编译器可以识别表2-8所示的标记。

表2-8

要了解它们的工作方式，可以在2.9.1小节的Calculator.cs文件中添加一些XML注释。我们给类及其Add()方法添加一个<summary>元素，也给Add()方法添加一个<returns>元素和两个<param>元素：

        // MathLib.cs
        namespace Wrox.MathLib
        {
          ///<summary>
          ///  Wrox.MathLib.Calculator class.
          ///  Provides a method to add two doublies.
          ///</summary>
          public class Calculator
          {
            ///<summary>
            ///  The Add method allows us to add two doubles.
            ///</summary>
            ///<returns>Result of the addition (double)</returns>
            ///<param name="x">First number to add</param>
            ///<param name="y">Second number to add</param>
            public static double Add(double x, double y) => x + y;
          }
        }