代码注释规范[转]

代码注释规范

 

一、             注释规范

1、    修改代码时，总是使代码的注释保持最新, 为了防止问题反复出现，对错误修复和解决方法代码必须使用注释。

2、    在每个函数、方法的开始，应该提供标准的注释以指示例程的用途，注释样本应该是解释它为什么存在和可以做什么的简短介绍。

3、    避免在代码行的末尾添加注释；行尾注释使代码更难阅读。

4、    在变量声明时，应在行尾添加注释；在这种情况下，将所有行尾注释应使用公共制表符（Tab）在一处对齐。

5、    避免杂乱的注释，如一整行星号。而是应该使用空白将注释同代码分开。

6、    在编写注释时使用通俗易懂的句子。注释应该阐明代码，而不应该增加多义性。

7、    对由循环和逻辑分支组成的代码使用注释。这些可以帮助源代码读者理解代码书写目的。

8、    在所有的代码修改处加上修改标识的注释，创建标识和修改标识由创建或修改人员的姓名加日期组成，如：磊20081216

9、    为了是层次清晰，在闭合的右花括号后注释该闭合所对应的起点。

10、在部署发布之前，移除所有临时或无关的注释，以避免在日后的维护工作中产生混乱。

二、             javascript脚本注释

1、    创建注释

/*

创建标识：汤晓磊磊20081216

方法功能描述：按行政区划编码，查询出符合条件的人员编码

使用的表：

使用的视图：

使用的存储过程：

参数描述：CantonCode：行政区划编码

*/

Function GetPeopleByCantonCode(CantonCode)

{

    …

}// 函数 GetPeopleByCantonCode 结束

2、    修改注释

/*

修改标识：磊20081216

修改内容：在查询语句中加入行政区划编码的限制条件

修改后测试人员确认标识：赵亮（小）20070416

*/

三、             C#文档注释

1、    创建注释

/// <summary>

/// 创建注释

        /// 创建标识：磊20081216

        /// 方法描述：按照行政区划编码，查询出符合条件的人员编码

/// 使用的表：

/// 使用的视图：

/// 使用的存储过程：

        /// </summary>

        /// <param name=" CantonCode ">行政区划编码</param>

/// <returns> Str ,查询的结果值</returns>

private string GetPeopleByCantonCode (string CantonCode)

        {

            …

            Retutn Str;

} // 方法 GetPeopleByCantonCode结束

2、    修改注释

/// <summary>

/// 创建注释

        /// 创建标识：磊20081216

        /// 方法描述：按照行政区划编码，查询出符合条件的人员编码

/// 使用的表：

/// 使用的视图：

/// 使用的存储过程：

        /// 修改注释

        /// 修改标识：磊20081216

/// 修改内容：在查询语句中加入行政区划编码的限制条件

/// 修改后测试人员确认标识：赵亮（小）20070416

        /// </summary>

        /// <param name=" CantonCode ">行政区划编码</param>

/// <returns> Str ,查询的结果值</returns>

private string GetPeopleByCantonCode (string CantonCode)

        {

            …

            Retutn Str;

} // 方法 GetPeopleByCantonCode结束

四、             SQL注释

1、    创建注释

/*

功能描述：

参数描述：

作者：

创建日期：

完成日期：

*/

2、    修改注释

/*

修改目的：

修改内容描述：

修改人：

修改日期：

完成日期：

*/