Coding Notes
1 CS类文件注释
1.1 规范 ：
由region来定义整个注释的区域, 其中包含region title, Type, 所属Module, 文件描述Description， Creator , Modified. 细节可参考以下注释:
# region File Information
//**
//* Type : Source Code
//* Module : TSDbDataReader
//* Description : Use to solve the problem on closing connection
//* Creator : sb - Monday, Sep 20, 2010
//* Modified : sb - Tuesday, Sep 21, 2010
//* sb - Wednesday, Sep 22, 2010
//*
# endregion
2 aspx 页面文件注释
1.1 规范:
详情请参考CS 类文件注释规范, 唯一的不同点就是在region外添加<%-- --%>, 以下为范例demo:
<%--
# region File Information
//**
//* Type : Aspx Page
//* Module : Budget Control
//* Description : Page of Default.aspx
//* Creator : sb - Monday, Sep 20, 2010
//* Modified : sb - Tuesday, Sep 21, 2010
//* sb - Wednesday, Sep 22, 2010
//*
# endregion
--%>
3 Function 方法注释
1.1 规范:
1.1.1 原则上, 在同一个CS类文件中将实现同一个 (类) 功能的方法, 事件放在同一个region中, 并在region title中对本段代码区域进行描述.
1.1.2 具体到每一个方法的注释, 可参考以下demo:
/// <summary>
/// Execute a SqlCommand that returns the first column of the first record against the database specified in the connection string
/// using the provided parameters.
/// </summary>
/// <param name="connectionString">a valid connection string for a SqlConnection</param>
/// <param name="commandType">the CommandType (stored procedure, text, etc.)</param>
/// <param name="commandText">the stored procedure name or T-SQL command</param>
/// <param name="commandParameters">an array of SqlParamters used to execute the command</param>
/// <returns>An object that should be converted to the expected type using Convert.To{Type}</returns>
public static object ExecuteScalar(string connectionString, CommandType cmdType, string cmdText, params SqlParameter[] commandParameters) {
SqlCommand cmd = new SqlCommand();
using (SqlConnection connection = new SqlConnection(connectionString)) {
PrepareCommand(cmd, connection, null, cmdType, cmdText, commandParameters);
object val = cmd.ExecuteScalar();
cmd.Parameters.Clear();
return val;
}
}
