代码注释规范
一、 注释规范
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、 修改注释
/*
修改目的:
修改内容描述:
修改人:
修改日期:
完成日期:
*/