C#注释：提升可读性的注解艺术

文章目录

• 注释
• 行注释
• 段注释
• XML注释
• 一级注释
• 二级注释
• 注释换行
• TODO注释

注释

行注释

// 注释内容

段注释

/* 注释内容 */

XML注释

/// <summary>
/// 注释内容
/// </summary>

/// 是智能注释也称xml注释，会在被编译，并生成xml文件在可执行文件中。会影响编译速度，但不会影响代码执行速度。

一级注释

<remarks> 对类型进行描述，功能类似 < summary>，据说建议使用 < remarks>;
<summary> 对共有类型的类、方法、属性或字段进行注释；
<value> 主要用于属性的注释，表示属性的制的含义，可以配合 < summary > 使用；
<param> 用于对方法的参数进行说明，格式：<param name="param_name">value</param>；
<returns> 用于定义方法的返回值，对于一个方法，输入 /// 后，会自动添加 < summary>、<param > 列表和 < returns>；
<exception> 定义可能抛出的异常，格式：<exception cref="IDNotFoundException">；
<example> 用于给出如何使用某个方法、属性或者字段的使用方法；
<permission> 涉及方法的访问许可；
<seealso> 用于参考某个其它的东东：)，也可以通过 cref 设置属性；
<include> 用于指示外部的 XML 注释；

二级注释

<c> or <code > 主要用于加入代码段；
<para> 的作用类似 HTML 中的 < p > 标记符，就是分段；
<pararef> 用于引用某个参数；
<see> 的作用类似 < seealso>，可以指示其它的方法；
<list> 用于生成一个列表；

另外，还可以自定义 XML 标签 。

注释换行

在 C# 智能注释时，常常希望它能在开发时显示为换行，使得提示更加友好！原来一直想怎么实现，今天偶然发现原来如此简单，只需将 <para>标记用于诸如 <summary>、<remarks>或 <returns>等标记内即可。

注释在开发时换行显示的办法
<para>标记用于诸如<summary>、<remarks> 或 <returns>等标记内，使您得以将结构添加到文本中。

注释在开发时换行显示的办法
<para>标记用于诸如<summary>、<remarks> 或 <returns>等标记内，使您得以将结构添加到文本中。

/// <summary> 
/// 基类（第 1 行） 
///<para> 说明：（第 2 行）</para> 
///<para>　　封装一些常用的成员（第 3 行）</para> 
///<para>　　前面要用全角空格才能显示出空格来（第 4 行）</para> 
/// </summary> 
public class MyBase 
{ 
      /// <summary> 
      /// 构造函数（第 1 行） 
      ///<para> 说明：（第 2 行）</para> 
      ///<para>　　初始化一些数据（第 3 行）</para> 
      /// </summary> 
      public MyBase() 
      { 
            // 
            //TODO: 在此处添加构造函数逻辑 
            // 
       } 
} 

TODO注释

TODO注释使用后，可以帮助记录项目中未完成的任务都有哪些。
在代码段里使用TODO注释，如
“//TODO：此处还没测试通过”

在 View -> Task List ，选择 Comments ，即可以查看项目中所有标记 TODO 的位置。

例：

注释在编程中扮演着重要的角色，它们是对代码的解释和说明，有助于理解代码、提高可读性和可维护性。以下是关于注释的总结：

1. 代码文档化: 注释是用来解释代码的目的、逻辑和实现细节的文本。良好的注释可以帮助其他开发者（包括你自己）更好地理解代码的含义和意图。

2. 不同类型的注释:

   • 单行注释: 使用 // 来添加单行注释，通常用于对代码的某一行或者某个部分进行解释说明。
   • 多行注释: 使用 /* */ 来添加多行注释，适合对一段代码块或者功能进行详细的解释。
   • XML 注释: C# 中的特殊注释，以 /// 开始，用于生成代码文档，可以包含标签如 <summary>, <param>, <returns> 等，提供了更结构化的文档说明。

3. 注释的内容:

   • 解释代码意图: 说明代码为什么要这样写，以及实现的逻辑思路。
   • 标识重要信息: 对于特殊处理、算法、设计决策等重要信息进行注释。
   • 提醒和警告: 在代码中标记潜在的问题、TODO、警告或需要注意的事项。
   • 版本控制信息: 记录代码修改、修复或版本更新的信息，以及作者、日期等相关信息。

4. 注释的最佳实践:

   • 保持清晰和简洁: 注释应该清晰、简明扼要，避免过度注释。
   • 更新维护: 随着代码的更新和变更，及时更新和维护注释以保持其与代码的一致性。
   • 注释不应重复代码: 注释应该解释为什么，而不是简单地描述代码在做什么。
   • 注释要有意义: 避免添加无效或者明显的注释，注释应该提供有价值的信息。

5. 注释的价值: 注释是协作和团队开发的重要工具，能够促进代码的理解、交流和维护。但过度注释也可能导致注释和代码不一致的问题，因此要平衡好注释的使用。

总的来说，良好的注释是良好编程实践的一部分，它们是帮助理解代码、传递信息、提高代码质量和可维护性的关键组成部分。

/// <summary>
/// 防御塔目标
/// <para>通过LockTarget锁定目标。</para> 
/// </summary>
protected Transform _target;// TODO 暂时为单个目标，后续需要改成列表。