编码规范-注释

1、源程序注释量需要达到代码总量的20%以上。

2、为类编写详细的说明性文件，格式如下：

/*************************************************
 * Author:lian_lekai       
 * Version:1.0.1        
 * Date: 2015-01-21
 * Description:后台管理系统主文件，主要作用是***************    
 * Others:
 * Function List:
 * 1、注册：***************
 * 2、登录：***************
 * 3、人员列表：***************
 * 4、设备列表：***************
 * 5、修改密码：***************
 * EditHistory: 
 * 1. Date:2015-02-11
 * Author:lian_lekai
 * Modification:管理员详情中的“查看详情”按钮与“设备详情”按钮跳转到一样的界面；完成注册功能。
 * 2. ...
*************************************************/

3、函数头部应进行注释，使用VS自带的格式。

/// <summary>
/// 使用post方法传递数据，并从服务器获取返回值
/// </summary>
/// <param name="json">发送给服务器的字符串</param>
/// <param name="url">服务器地址</param>
/// <returns>返回服务器返回的字符串</returns>
public string Post(string json , string url)
{
    ...
}

4、对所有有具体含义的的变量和常量进行注释，位置为变量的上方或右方。
说明：使用“//”进行注释

5、全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。
说明：注释格式如下：

/*
* function:服务器地址
* valueScope:fixed
* note:该变量存放的是服务器的地址，只能进行访问，不能改变。只提供了get访问器。
*/
private string g_ip="http://121.40.194.174:13000/";
public string Ip
{
    get
        {
            return g_ip;
    }
}

7、for循环，while语句等控制语句必须进行注释。由其是switch语句中的case语句。
说明：使用“//”进行注释。

8、通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。
说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。