首页 > 代码库 > 自己总结的C#编码规范--4.注释约定

自己总结的C#编码规范--4.注释约定

  • 注释

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

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

  • 注释约定

如果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. 如果客户方没有对注释特殊要求,那么按照下文中讨论的只在需要的地方加注释。不要加无谓的注释。