浅谈编码习惯之注释篇

Posted 2020-10-03 tiger_yj

　　软件编码过程中，当注释代码时，要考虑到不仅将来维护你代码的开发人员要看，而且你自己也可能要看。用Phil Haack大师的话来说就是：“一旦一行代码显示屏幕上，你也就成了这段代码的维护者”。因此，对于我们写得好(差)的注释而言，我们将是第一个受益者(受害者)。以下是我个人的简单看法和平常的习惯。

       1、模块注释

　　在一个程序模块的开始，应用注释说明模块的名字、功能、开发者和日期和版本变更历史，如下所示：

/******************************************************************
 * Copyright(c)   :  TigerSoft 
 * Description     : Lern access class
 * CreateDate     : 2017-06-02 
 * Creater           : Liu  
 * UpdatedDate   : 
 * Updater           : 
 * ******************************************************************/ 

　　2、单行注释

　　程序员应当在算法比较复杂的表达式前、特殊含义的变量前或者在一整段功能代码开始之前添加适当的注释。例如：

// Calculate sum
Decimal sum= 0;

　　3、类注释

　　在定义一个类之前，应用“///”注释说明类的功能、使用方法和特殊的属性，如下所示：

/// <summary>
/// This class...
/// <remarks>
/// Please note …
/// </remarks>
/// </summary>

　　4、方法注释

　　在定义类成员方法前，应说明该过程/函数的名字、功能、输入/输出和版本变更历史，如下所示：

/// <summary>
///  This method ….
/// <param name="param1">this is a param of the method SumMethod.</param>
/// <retvalue>a return object</retvalue>
/// </summary>
//-------------------------------------------------------------------------------------------------
// Change History:
// Date            Who                    Changes Made
// 2017-5-1        Author1        Initial creation
// 2017-7-15        Author2        Add some code
//-------------------------------------------------------------------------------------------------
public object SumMethod(object param1)
{
}