三种注释

注释是什么

是代码中添加一些帮助程序员理解的文本，注释不属于代码的一部分，编译器不会编译，编译器会忽略这些注释的内容。

有时候我们可以理解注释来进行问题排查，例如遇到问题，不知道哪里，可以通过注释一些你认为出错的代码，这些代码注释后，编译器会忽略它，从而进行问题排查。

注释就好比，我们上学时候，给课本增加的注解笔记，这些注解有利于我们理解课文。

注释的种类

注释类型	起始标记	结束标记	核心规则
单行注释 Single-line	//	本行末尾	仅作用当前整行，本行//后全部忽略
块注释（分隔注释）Delimited	/*	*/	跨任意多行/行内片段，不可嵌套
文档注释 Documentation	///	本行末尾	内置XML标签，用于自动生成项目API文档

1. 单行注释 //

1. 从//开始，直到当前行结尾全部被编译器忽略；
2. 可写在行首或者代码后方；
3. 无嵌套限制，不会和/* */冲突。

// 行首单行注释：定义数字变量
int num = 10; // 代码后单行注释：存储数值10
// int temp = 99; // 整行代码注释屏蔽 可以用于调试排查问题 临时让一些代码不执行，但是又不删除它们，方便后面重新恢复Code language: JavaScript (javascript)

2. 块注释 /* */

1. 起止成对标记，中间所有内容忽略；/*开始 */结束
2. 支持跨多行，也支持行内局部注释；
3. 禁止嵌套块注释，编译器遇到第一个*/就直接结束注释，剩余*/会报语法错误。

例子

/*
多行块注释示例
所有内容编译器都会跳过
可以写任意多行文字
*/
string str = "测试";Code language: JavaScript (javascript)

/*
Multi-line delimited comment example
All content here is ignored by the compiler
Text can span any number of lines
wellcome to foxdevelop.com
*/
string greet = "wellcome to foxdevelop.com";
Console.WriteLine(greet);Code language: JavaScript (javascript)

如果嵌套会报错

在块注释里面又有一个块注释，导致最后一个结束注释，没有和它匹配的开始注释，所以报错了。

行内局部注释

仅屏蔽片段代码，如下的a变量被注释了。

int /*a,*/ b; 
// 等效 int b; 中间a,被注释屏蔽Code language: JavaScript (javascript)

错误嵌套块注释

报错

/* 外层注释开始
    /* 内层嵌套注释（无效，已被当作普通文本） */
// 上面第一个*/直接关闭外层注释，下面这个*/无匹配开头，语法报错
*/Code language: JavaScript (javascript)

//内写/*不触发块注释

相当于 这个块注释被注释了。

// 这是单行注释 /* 这里的/*只是普通文字，不会开启块注释
int x = 5;
/* 开启块注释 */ // 块注释结束，后面//正常生效Code language: JavaScript (javascript)

3. 文档注释 ///

1. 外观类似单行注释，三连斜杠///；
2. 内置XML标签，IDE/工具可读取生成API帮助文档；
3. 一般写在类、方法、属性上方，用于对外接口说明。

/// <summary>
/// 程序入口主类
/// </summary>
class Program
{
    /// <summary>
    /// 程序入口方法
    /// </summary>
    /// <param name="args">命令行参数数组</param>
    static void Main(string[] args)
    {

    }
}Code language: C# (cs)

总结

1. 块注释/* */不能嵌套，首个*/直接终止注释；
2. //单行注释仅作用本行，不会跨行，内部/*不开启块注释；
3. C#单行、块注释语法行为与C/C++完全一致；
4. 注释编写原则：不重复复述代码字面含义，重点说明代码业务目的、设计思路，方便后期维护；仅复述变量名的注释无价值。
5. 单行简短说明、临时屏蔽单行代码 → //
6. 批量屏蔽多行代码、行内局部屏蔽片段 → /* */
7. 给类/方法写接口说明、生成项目文档 → ///

* 如何生成文档

下面是参考，对于大型项目才会用到文档注释，我们学习阶段，理解有这个东西就可以。

Visual Studio 操作

1. 右键项目 → 属性 → 生成 (Build)；
2. 勾选：生成 XML 文档文件 (Generate XML documentation file)；
3. 输出路径默认：bin\Debug\项目名.xml，可自定义路径；
4. 全部配置 (All Configurations) 勾选，Debug/Release 都生效；
5. 重新生成项目，目录下会出现完整 XML 注释文件。

.NET CLI 命令行配置（无 VS 时）

编辑项目 .csproj 文件，添加节点：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
Code language: HTML, XML (xml)

执行生成：

dotnet build

作用

这个 XML 文件存储所有<summary>、<param>、<returns>等注释内容，是生成文档的数据源；同时 VS 会读取它，在 IntelliSense 悬浮提示显示注释。

其他工具

微软还提供DocFX（微软官方推荐，最简单，生成静态 HTML 网站）

Sandcastle（微软老牌工具，生成 CHM 离线帮助文件）

第三方轻量化（如 Doxygen）