编码规范V100.doc

1 24 编号 GF Code V1 0 0 C 编码规范编码规范 保密级别 保密保密级别 保密 文件标识 GF Code V1 0 当前版本 V1 0 0 作 者 谢换青 审 核 文件状态 草稿文件 正式文件 更改正式文件 完成日期 2011 11 11 2 24 版本历史版本历史 版本 状态作者参与者起止日期备注 V1 0 0 谢换青2011 09 10 至 2011 11 11 3 24 目目 录录 1 1 文档描述文档描述 5 1 1 目的 5 1 2 读者对象 5 1 3 适用范围 5 1 4 定义 5 2 2 编程准则编程准则 5 2 1 变量使用 5 2 2 数据库操作 6 2 3 对象使用 6 2 4 结构化要求 6 2 5 函数返回值原则 7 2 6 关键字使用原则 7 2 7 架构使用原则 7 3 3 编码规则编码规则 7 3 1 错误检查规则 7 3 2 大括号规则 8 3 3 缩进规则 9 3 4 If Then Else 规则 9 3 5 Switch Case 规则 10 3 6 单语句规则 10 3 7 单一功能规则 10 3 8 独立赋值规则 10 3 9 模块化规则 10 3 10 交流规则 11 4 4 命名规范命名规范 11 4 1 命名规范 11 4 2 变量 Variable 命名 11 4 3 常量 const 命名 14 4 4 类 Class 命名 14 4 24 4 5 接口 Interface 命名 15 4 6 方法 Method 命名 15 4 7 命名空间 NameSpace 命名 15 5 5 注释规范注释规范 15 5 1 概述 15 5 2 自建代码文件注释 16 5 3 模块 类 注释 16 5 4 类属性注释 17 5 5 方法注释 17 5 6 代码间注释 17 6 6 代码包的版本号代码包的版本号 18 6 1 代码包的标识 18 7 7 输入控制校验规则输入控制校验规则 19 8 8 附件附件 19 8 1 控件缩写前缀 19 5 24 1 1 引言引言 1 11 1 目的目的 为了统一公司软件开发的设计过程中关于代码编写时的编写规范和具体开发工作 时的编程规范 保证代码的一致性 便于交流和维护 特制定此规范 1 21 2 读者对象读者对象 参与本项目开发工作的软件工程师 1 31 3 适用范围适用范围 软件项目开发的代码编写阶段和后期维护阶段 1 41 4 定义定义 灰色字体表示部分为优先原则 非必行约定 蓝色字体表示部分为代码演示部分 绿色字体表示部分为代码注释演示部分 格式描述中 符号 表示必选元素 格式描述中 符号 表示可选元素 2 2 编程准则编程准则 2 12 1 变量使用变量使用 a 一个变量只能有一个用途 变量的用途必须和变量的名称保持一致 b 所有变量都必须在类和函数最前面定义 并分类排列 6 24 2 22 2 数据库操作数据库操作 a 查找数据库表或视图时 只能取出确实需要的那些字段 b 使用无关联子查询 而不要使用关联子查询 c 清楚明白地使用列名 而不能使用列的序号 d 用事务保证数据的完整性 2 32 3 对象使用对象使用 a 尽可能晚地创建对象 并且尽可能早地释放它 b 关于对象的创建 尽量使用工厂模式集中生产 2 42 4 结构化要求结构化要求 a 禁止出现两条等价的支路 例如 if a 2 else if a 3 else if a 2 else b 避免使用 GOTO 语句 c 用 IF 语句来强调只执行两组语句中的一组 尽量不使用 ELSE GOTO 和 ELSE RETURN d 用 Switch Case 实现多路分支 避免使用多 IF 嵌套 e 避免从循环引出多个出口 f 函数只有一个出口 7 24 g 在同一个类中读写数据源数据要保持一致 如 class hello private string Name public string Name Get return Name Set Name value Public string GetName 这里应该读写 Name 属性应该统一为 this Name 而不是 Name If string isNullOrEmpty this Name Return string format My name is 0 this Name 2 52 5 函数返回值原则函数返回值原则 1 函数返回值 避免使用结构体等复杂类型 8 24 2 62 6 关键字使用原则关键字使用原则 1 partial 关键字必需只作用于同一架构层上 在不同架构层上需要实现同 一个类功能的 使用继承 2 partial 关键字最好只作用于同一命名空间上 2 72 7 架构使用原则架构使用原则 1 低层类不允许使用高层类 2 低层类库不允许引用高层类库 3 3 编码编码规则规则 3 13 1 错误检查规则错误检查规则 a 编程中要考虑函数的各种执行情况 尽可能处理所有流程情况 b 检查所有的系统调用的错误信息 除非要忽略错误 c 将函数分两类 一类为与屏幕的显示无关 另一类与屏幕的显示有关 对于 与屏幕显示无关的函数 函数通过返回值来报告错误 对于与屏幕显示有关的函数 函数要负责向用户发出警告 并进行错误处理 d 错误处理代码一般放在函数末尾 e 对于通用的错误处理 可建立通用的错误处理函数 处理常见的通用的错误 f 异常必须有效处理 如果不能有效处理 请直接抛出 不做处理 避免扑捉 异常也不处理的情况 3 23 2 大括号规则大括号规则 a 将大括号放置在关键词下方的同列处 例如 9 24 if condition while condition b 在大括号多重嵌套时 后加 结构关键字 例如 if condition while condition if condition 测试 Else if while 3 33 3 缩进规则缩进规则 使用一个 Tab 为每层次缩进 例如 function func 10 24 if something bad if another thing bad while more input 3 43 4 IfIf ThenThen ElseElse 规则规则 如果你有用到 else if 语句的话 通常最好有一个 else 块以用于处理未处理到 的其他情况 可以的话放一个记录信息注释在 else 处 即使在 else 没有任何的动 作 其格式为 该 if 嵌套块的注释 注 说明其任务职能 if 条件 1 条件 1 分支描述 else if 条件 2 条件 2 分支描述 else 条件分支描述 注 if 和循环的嵌套最多允许 4 层 多路分支建议使用用 Switch Case 参考 编程准则 结构化要求 11 24 3 53 5 Switch Switch Case Case 规则规则 default case 总应该存在 如果不允许到达 则应该保证 若到达了就会触发 一个错误 3 63 6 单语句规则单语句规则 除非这些语句有很密切的联系 否则每行只写一个语句 3 73 7 单一功能规则单一功能规则 原则上 一个程序单元 函数 例程 方法 只完成一项功能 3 83 8 独立赋值规则独立赋值规则 嵌入式赋值不利于理解程序 同时可能回造成意想不到的副作用 应尽量编写独 立的赋值语句 例如 使用 a b c e a d 而不用 e a b c d 3 93 9 模块化规则模块化规则 某一功能 如果重复实现一遍以上 即应考虑模块化 将它写成通用函数 并记 录到公用函数表 向小组成员发布 同时要尽可能利用其它人的现成模块 3 103 10 交流规则交流规则 共享别人的工作成果 向别人提供自己的工作成果 在具体任务开发中 如果有其它的编码规则 则在相应的软件开发计划中予以明 确定义 12 24 4 4 命名规范命名规范 4 14 1 命名规范命名规范 类名或变量名等 不用前缀 控件需使用前缀 注 变量名和常量名最多可以包含 255 个字符 但是 超过 25 到 30 个字符 的名称比较笨拙 此外 要想取一个有实际意义的名称 清楚地表达变量或常量的 用途 25 或 30 个字符应当足够了 4 24 2 变量 变量 VariableVariable 命名 命名 a 程序文件 cs 中的变量命名 类模块级的变量使用 m 英文单词或单词缩写 类的属性所对应的变量 使用 英文单词或单词缩写 英文单词或单词缩写部分 每个单词的首写母大写 public class hello private string mSellerName private DateTime mBirthday 类的属性名称 每个单词的首写字母大写 如果此属性有对应的变量 则此属性名称 为此变量名去掉前面的 并且第一个单词的首写字母变为大写 public class hello private string sellerName public string SellerName get 13 24 return sellerName 方法内的变量可以使用缩写格式 temp 英文单词或单词缩写 英文单词或单 词缩写部分 每个单词的首写母大写 方法的参数第一个单词小写 之后的单词的首写字母大写 public class hello void say string tempSayWord public class hello void say string sayWord 补充说明 针对异常捕获过程中的 Exception 变量命名 在没有冲突的情况下 统一命名为 ex 如果有冲突的情况下 可以用 ex 标志名称 如 exSql Try your code try 14 24 code catch Exception ex your code catch Exception exSql your code 补充 如果捕获异常不需要作任何处理 则不需要定义 Exception 实例 例 try your code catch 即使对于可能仅出现在几个代码行中的生存期很短的变量 仍然使用有意义的名 称 仅对于短循环索引使用单字母变量名 如 i 或 j 在变量名中使用互补对 如 min max begin end 和 open close 不要使用原义数字或原义字符串 如 For i 1 i 7 i 而是使用命名 常数 如 For i 1 i NUM DAYS IN WEEK i 以便于维护和理解 b 控件命名 15 24 控件命名 控件缩写前缀 参考 附件 控件缩写前缀 名称 如 一个用来 展示用户信息的 DataGrid 命名 dg UserList dgUserList 4 34 3 常量 常量 constconst 命名 命名 常量名也应当有一定的意义 格式为 NOUN 或 NOUN VERB 常量名均为大写 字 之间用下划线分隔 例 private const bool WEB ENABLEPAGECACHE DEFAULT true private const int WEB PAGECACHEEXPIRESINSECONDS DEFAULT 3600 private const bool WEB ENABLESSL DEFAULT false 4 44 4 类 类 ClassClass 命名 命名 a 名字应该能够标识事物的特性 b 名字尽量不使用缩写 除非它是众所周知的 c 名字可以有两个或三个单词组成 但通常不应多于三个 d 在名字中 所有单词第一个字母大写 例如 IsSuperUser 包含 ID 的 ID 全 部大写 如 CustomerID e 使用名词或名词短语命名类 f 少用缩写 例 public class FileStream public class Button public class String 4 54 5 接口 接口 InterfaceInterface 命名 命名 和类命名规范相同 唯一区别是 接口名称 I 实现类名称 例 16 24 interface IDBCommand interface IButton 4 64 6 方法 方法 MethodMethod 命名 命名 和类命名规范相同 4 74 7 命名空间 命名空间 NameSpaceNameSpace 命名 命名 和类命名规范相同 5 5 注释规范注释规范 5 15 1 概述概述 a 注释中 应标明对象的完整的名称及其用途 但避免对代码过于详细的描述 b 编码的同时书写注释 c 重要变量必须有注释 d 变量注释和变量在同一行 所有注释必须对齐 如 int iLevel iCount iLevel 级别 iCount 数量 string strSql SQL 语句 e 典型算法必须有注释 f 在循环和逻辑分支地方的上行必须就近书写注释 g 程序段或语句的注释在程序段或语句的上一行 17 24 5 25 2 自建代码文件注释自建代码文件注释 对于自己创建的代码文件 如函数 脚本 在文件开头 一般编写如下注释 FileName Copyright c 时间 公司 Writer create Date Rewriter Rewrite Date Remark 5 35 3 模块 类 注释模块 类 注释 模块开始必须以以下形式书写模块注释 Module ID Depiction Author 作者中文名 Create Date 5 45 4 类属性注释类属性注释 在类的属性必须以以下格式编写属性注释 18 24 5 55 5 方法注释方法注释 在类的方法声明前必须以以下格式编写注释 depiction param name 5 65 6 代码间注释代码间注释 代码间注释分为单行注释和多行注释 单行注释 多行注释 6 6 代码包的版本号代码包的版本号 项目中 代码包的版本号由圆点隔开的两个数字组成 第一个数字表示发行号 第二个数字表示该版的修改号 具体用法如下 19 24 1 当代码包初版时 版本号为 V1 00 2 当代码包被局部修改或 bug 修正时 发行号不变 修改号第二个数字增 1 例如 对初版代码包作了第一次修订 则版本号为 V1 01 3 当代码包在原有的基础上增加部分功能 发行号不变 修改号第一个数字增 1 例如 对 V1 12 版的基础上增加部分功能 则新版本号为 V1 20 4 当代码包有重要修改或局部修订累积较多导致代码包发生全局变化时 发行 号增 1 例如 在 V1 15 版的基础上作了一次全面修改 则新版本号为 V2 00 6 16 1 代码包的标识代码包的标识 项目所产生的代码包都有唯一 特定的编码 其构成如下 S 项目标识 代码包类型 版本号 序号 其中 1 S 本项目的标识 表明本项目是 XXXX 2 项目标识 简要标识本项目 此标识适用于整个项目的文档 3 代码包类型 取自以下表的两位字母编码 4 版本号 本代码包的版本号 5 序号 四位数字编码 指明该代码包在项目代码库的总序号 例如 一个 Windows 下 RAR 源码的压缩代码包命名为 S XXXX WS V1 02 0001 项目的代码包分类表 类 型编 码注 释 源码文件 WS 源代码文件包 编译文件 WB 编译文件包 安装文件 WI 安装文件包 RAR 包 Windows 源码代码 安装文 件 WA 源代码和安装文件包 源码 RSSource in rpm Rpm 包 Linux 二进制代码 REExecution in rpm 20 24 源码 TSSource in tar gz 二进制代码 TEExecution in tar gz tar gz 包 Linux 源码 二进制代码 TA Source Execution in tar gz 项目中所有代码包的标识清单将在 项目开发计划 中予以具体定义 7 7 输入控制校验规则输入控制校验规则 1 所有数字类型的录入收集框必须加数字验证 2 所有非空字段必须加验证 8 8 附件附件 8 18 1 控件缩写前缀控件缩写前缀 a Web 控件 Web 控件名缩写 AdRotatorart Buttoncmd Calendarcd CheckBoxchk CheckBoxListchkl CompareValidatorcpv CustomValidatorctv DataGriddg DataLi