• 注释

注释毫无疑问是让别人以最快速度了解你代码的最快途径，但写注释的目的绝不仅仅是"解释代码做了什么"，更重要的尽量帮助代码阅读者对代码了解的和作者一样多。

当你写代码时，你脑海里会有很多有价值的信息，但当其他人读你代码时，这些信息已经丢失，他们所见到的只是眼前代码。

• 注释约定

如果IDE提供注释格式，则尽量使用IDE提供的格式，否则使用"//"来注释。类、属性和方法的注释在Visual Studio中都使用输入"///"自动生成的格式。

• 类注释约定

/// <summary>

/// 类说明

/// </summary>

public class BinaryTree

• 类属性注释约定

/// <summary>

/// 属性说明

/// </summary>

public int NodesCount { get; private set; }

• 方法注释约定

/// <summary>

/// 方法说明

/// </summary>

/// <param name="parentNode">参数说明</param>

/// <returns>返回值说明</returns>

public int ComputeChildNodesCount(BinaryNode parentNode)

• 代码间注释约定

1. 单行注释，注释行数<3行时使用

   //单行注释

2. 多行注释，2<注释行数<=10时使用

   /*多行注释1

   多行注释2

   多行注释3*/

3. 注释块，10<注释行数时使用，用50个*

   /***************************************************

   * 代码块注释1

   *    代码块注释2

   *    ......

   *    代码块注释10

   *    代码块注释11

   ***************************************************/

• 何时写注释的约定

1. 以下三种情况我们需要在所有的类、类属性和方法都必须按照上述格式编写注释
   1. 客户方对代码注释重视程度较高
   2. 我们需要提供代码注释自动生成的API文档。

   

   1. 目前编写的是公共核心模块
2. 如果客户方没有对注释特殊要求，那么按照下文中讨论的只在需要的地方加注释。不要加无谓的注释。