首页 > 代码库 > 自己总结的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)
代码间注释约定
- 单行注释,注释行数<3行时使用
//单行注释
- 多行注释,2<注释行数<=10时使用
/*多行注释1
多行注释2
多行注释3*/
- 注释块,10<注释行数时使用,用50个*
/***************************************************
* 代码块注释1
* 代码块注释2
* ......
* 代码块注释10
* 代码块注释11
***************************************************/
何时写注释的约定
- 以下三种情况我们需要在所有的类、类属性和方法都必须按照上述格式编写注释
- 客户方对代码注释重视程度较高
- 我们需要提供代码注释自动生成的API文档。
- 目前编写的是公共核心模块
- 如果客户方没有对注释特殊要求,那么按照下文中讨论的只在需要的地方加注释。不要加无谓的注释。