【教程】使用XML注解CSharp代码内容

---

Microsoft 官方文档链接：XML 文档注释

---

编程平台：Visual Studio 2022
编程语言：CSharp
 

一、为什么有此文章

---

  如果说写程序是为了达到某种实现效果目的而做的事情，那么写注释是为了将代码负责的托付给下一位。（当然也是更快让自己失业）。在对工作上，除必要的代码行做出解释，多数情况下并不需要做到对任一的详细描述。大概一二即可，但对自己，譬如开发一套适用于个人搞搞小业务的时候。整理前后显得尤为重要。本文重点概括总结个人使用频率较高的XML关键词。
 

二、XML 关键词

---

2.1 特殊注释字段 | summary

• 常用于 Classs/Struct、Property、Method 、Event/Action/Delegate，以简洁明了的描述解释用途。

2.2 概述说明字段 | remarks

• 类名的简述是必须必然的，以快速告诉开发者它的主要用途。而 remarks 等同于一段内容描述，以补充作为标题字段的 Summary 所无法阐述的内容。与 return 相比较，其适用属性、字段、方法、类等较为广泛。但倾向上更适用于非泛型对象。

2.3 返回结果字段 | returns

• 常用于 泛型 或 特定类型 Method，以解释该方法返回对象或内容。但注意，无论条件是否成立，可以返回null或new，根据应用环境，必要时应添加结果返回说明参数。亦或是默认值。

2.4 参数注释字段 | param 与 typeparam

• 默认设置下，对不存在于该方法内的变量对象，使用该注释字段将显示白色。虽不影响代码运行，但建议删除非方法需要变量对象的XML描述项。
  • param 字段伴随指引方法内需引用的局部变量解释。
  • typeparam：用于 T 泛型参数的解释

2.5 链接引用字段 | see

• 多用于引用说明，例如使用同类方法、链接地址等内容。需搭配 cref/herf 注明引用对象后，其字段内容均以蓝色超链接方式存在。
  • cref：用于引用类成员 + 字段
  • herf：用于引用链接地址