软件开发编码规范

软件开发编码规范软件开发编码规范 C C 2 目 录 1引言 4 1 1编写目的 4 1 2背景 4 1 3定义 4 1 4参考资料 4 2基本要求 4 2 1程序结构要求 4 2 2可读性要求 4 2 3结构化要求 5 2 4正确性与容错性要求 5 2 5可重用性要求 6 3用户界面设计原则 6 4源程序书写规范 6 4 1通用源代码格式规则 6 4 1 1缩进 6 4 1 2边距 7 4 1 3 的使用 7 4 1 4注释 7 4 2语句格式与语句书写规范 7 4 2 1括号 8 4 2 2保留字和关键字 8 4 2 3函数 8 4 2 4变量 8 4 2 5语句 8 5命名规范 10 5 1函数命名 10 5 2形参 10 5 3常量和变量 10 5 3 1常量和宏定义 10 5 3 2变量 10 5 4函数使用说明 接口命名 NameSpace 命名 11 5 5控件的命名 12 5 6类型 12 5 6 1一般类型 12 5 6 2构造类型 13 5 6 3类类型 13 5 7文件和文件夹 13 5 7 1文件夹的命名规则 13 5 7 2文件命名 14 6源程序文档注释规范 14 6 1注释文档的一般规范 14 3 1 1 引言引言 1 11 1编写目的编写目的 本规范旨在用规范文件的形式 对全公司使用 C 进行的编程过程 进行有效的规范 管理 使得最终的软件产品具有良好的风格和统一的结构 且使代码可读性强 易维 护 本规范预期读者是全公司所有参与编程的软件开发人员以及其他相关人员 本标准适用于 Visual C 其余语言作参考 1 21 2背景背景 公司在上一个项目中由于代码编写风格不统一 可读性较差 较难维护 使得工作 效率有所降低 1 31 3定义定义 无 1 41 4参考资料参考资料 Pascal Standards FAQ E JavaDoc E Doc O matic Document E Artemis Alliance Delphi Coding Standards E C 基本书写规范 C 编码规范纲要 2 2 基本要求基本要求 2 12 1程序结构要求程序结构要求 程序结构清晰 简单易懂 单个函数的程序行数一般不得超过 100 行 个别特殊函 数除外 代码中打算干什么 要简单 直接了当 代码精简 避免垃圾程序 应尽量使用 NET 库函数和公共函数 无特殊情况不要使用外部方法调用 windows 的 核心动态链接库 一般情况下 不得使用全局变量 尽量使用局部变量 2 22 2可读性要求可读性要求 可读性第一 效率第二 这仅对代码本身而言 保持注释与代码完全一致 4 每个源程序文件 都必须有文件头说明 说明规格见 源程序文档注释规范 一节 每个函数 都必须有函数头说明 说明规格见 源程序文档注释规范 一节 主要变量 结构 联合 类或对象 定义或引用时 注释必须能反映其物理含义 处理过程的每个阶段都必须有相关注释说明 在典型算法前都必须有注释 同时算法在满足要求的情况下应尽可能简单 利用缩进来显示程序的逻辑结构 缩进量一致以 Tab 键为单位 定义 Tab 为 4 个 字节 循环 分支层次不要超过五层 注释可以与语句在同一行 也可以在上行 空行和空白字符也是一种特殊注释 一目了然的语句不加注释 注释的作用范围可以为 定义 引用 条件分支以及一段代码 注释行数 不包括文件头和函数头说明部份 应占总行数的 1 5 到 1 3 常量定义 const 有相应说明 2 32 3结构化要求结构化要求 禁止出现两条等价的支路 禁止 GOTO 语句 用 IF 语句来强调只执行两组语句中的一组 禁止 ELSE GOTO 和 ELSE RETURN 用 CASE 实现多路分支 避免从循环引出多个出口 函数只有一个出口 不使用复杂的条件赋值语句 避免不必要的分支 不要轻易用条件分支去替换逻辑表达式 2 42 4正确性与容错性要求正确性与容错性要求 程序首先是正确 其次是优美 无法证明你的程序没有错误 因此在编写完一段程序后 应先回头检查 改一个错误时可能产生新的错误 因此在修改前首先考虑对其它程序的影响 所有变量在调用前必须被初始化 对所有的用户输入 必须进行合法性检查 不要比较浮点数的相等 如 10 0 0 1 1 0 不可靠 程序与环境或状态发生关系时 必须主动去处理发生的意外事件 如文件能否逻辑 锁定 打印机是否联机等 对于明确的错误 要有明确的容错代码提示用户 单元测试也是编程的一部份 提交联调测试的程序必须通过单元测试 尽量使用规范的容错语句 例如 try 5 catch finally 2 52 5可重用性要求可重用性要求 重复使用的完成相对独立功能的算法或代码应抽象为服务或类 服务或类应考虑面向对象 OO 思想 减少外界联系 考虑独立性或封装性 3 3 用户界面设计原则用户界面设计原则 除标题部分外 所有显示给用户的字体 如BUTTON和LABEL等 使用标准字体 宋 体 九号 黑色 标题部分可用醒目的字体 如 宋体 小二号 红色 采用Windows缺省的风格 窗体尽量从已有的父窗体继承 方便用户对信息的输入 修改和阅读 验证用户输入的有效性和合理性 具有清晰明确的用户提示信息 使用Tab键在输入项之间移动输入焦点 可选 标准按钮大小必须相同 使用的图像和标题必须与 界面风格规范 一致 如果出现 该规范中没有的地方 须与项目负责人和美工协商 4 4 源程序书写规范源程序书写规范 4 14 1通用源代码格式规则通用源代码格式规则 4 1 14 1 1 缩进缩进 缩进就是每级间有一个 Tab 单位 不要在源代码中放置制表符 这是因为 制表符 的宽度随着不同的设置和代码管理实用程序 打印 文档及版本控制等 而不同 沿逻辑结构行缩进代码 没有缩进 代码将变得难以理解 如 if expression 此处填写你的代码块 if expression 此处填写你的代码块 6 else 此处填写你的代码块 缩进代码会产生出更容易阅读的代码 如 if expression if expression 此处填写你的代码块 else 此处填写你的代码块 4 1 24 1 2 边距边距 边距设置为 80 个字符 源代码一般不会因写一个单词而超过边距 但本规则比较 灵活 只要可能 长度超过一行的语句应当用分行符换行 换行后 应缩进两个字符 4 1 34 1 3 的使用的使用 或 必须单独占一行 例如 错误形式 for i 0 i 10 i 错 与 f o r 在同一行 正确形式 for i 0 i 10 i 对 在另外一行中 4 1 44 1 4 注释注释 通常使用 类型的块注释和 类型的行注释 7 4 24 2语句格式与语句书写规范语句格式与语句书写规范 4 2 14 2 1 括号括号 在左括号与下一字符之间没有空格 同样 右括号与前一字符也没有空格 下面的 例子演示了正确与不正确的空格 CallProc aParameter 错 CallProc aParameter 正确 4 2 24 2 2 保留字和关键字保留字和关键字 在用户的各种命名中不能单独使用保留字或关键字来进行命名 4 2 34 2 3 函数函数 4 2 3 14 2 3 1 格式格式 函数名要能体现出该函数要实现的功能 应当以大写字母开始 且大小写交错以 增加可读性 每个单词的首字母大写 下面是一个不正确的写法 pubilc void thisisapoorlyformattedroutinename 下面是正确的写法 pubilc void ThisIsMuchMoreReadableRoutineName 4 2 3 24 2 3 2 形参形参 1 1 参数顺序参数顺序 形参的顺序主要要考虑寄存器调用规则 最常用的参数应当作为第一个参数 按使 用频率依次从左到右排 输入参数位于输出参数之前 范围大的参数应当放在范围小 的参数之前 例如 SomeProc aPlanet aContinent aCountry aState aCity 有些则例外 例如 在事件处理过程中 Object 类型的 Sender 参数往往是第一个 要传递的参数 2 2 常量参数常量参数 任何值类型参数 只要不加REF标志 都是常量参数 任何引用类型参数 都不是常量参数 不管加不加标志 4 2 44 2 4 变量变量 4 2 4 14 2 4 1 局部变量局部变量 局部变量用于过程内部 如果需要的话 应当在过程的入口处立即初始化变量 4 2 4 24 2 4 2 全局变量全局变量 一般不鼓励使用全局变量 不过 有时候需要用到 即使如此 也应当把全局变量 限制在需要的环境中 例如 一个全局变量可能只在单元的实现部分是全局的 全局数据如果将由许多单元使用 就应移动到一个公用单元里被所有对象使用 全 局数据可在声明时直接初始化为一个值 4 2 54 2 5 语句语句 4 2 5 14 2 5 1 IfIf 语句语句 8 在 if else 语句中 if 子句的条件应该直接且易于理解 为了避免出现许多 if 语句 可以使用 switch 语句代替 如果多于 5 级 不要使用 if 语句 请改用更清楚的方法 如果在 if 语句中有多个条件要测试 应按照计算的复杂程度从右向左排 这样 可 以使代码充分利用编译器的短路估算逻辑 例如 如果 Condition1 比 Condition2 快 Condition2 比 Condition3 快 则 if 语句一般应这样构造 if Condition1 Condition2 Condition3 如果 Condition3 为 False 的机会很大 利用短路估算逻辑 我们也可以将 Condition3 放在最前面 if Condition3 Condition1 Condition2 有 if 出现 就必须有对应的 else 出现 if 语句的三种形式 1 形式一 不需要 else if Condition Process else No Else Needed 2 形式二 需要 else 但是 else 里面不需要处理 if Condition Process else No Need Process 3 形式三 if 里面不需要处理 if Condition No Need Process else Process 4 2 5 24 2 5 2 switchswitch 语句语句 1 1 概述 概述 switch 语句中每种情况的常量应当按数字或字母的顺序排列 每种情况的动作语句 应当简短且通常不超过 4 5 行代码 如果动作太复杂 应将代码单独放在一个函数 中 switch 语句的 else 子句只用于默认情况或错误检测 2 2 格式 格式 9 switch 语句遵循一般的缩进和命名规则 4 2 5 34 2 5 3 whilewhile 语句语句 所有对 while 循环进行初始化的代码应当位于 while 入口前 且不要被无关的语句隔 开 任何业务的辅助工作都应在循环后立即进行 4 2 5 44 2 5 4 forfor 语句语句 如果循环次数是确定的 应当用 for 语句代替 while 语句 5 5 命名规范命名规范 5 15 1函数命名函数命名 函数名应当有意义 进行一个动作的函数最好在名称前加上表示动作的动词为前缀 例如 public void FormatHardDrive 设置输入参数值的函数名应当以 Set 为其前缀 例如 public void SetUserName 获取数值的函数名应当以 Get 为其前缀 例如 public string GetUserName 函数名称第一个字母必须使用大写字母 要求用大小写字母组合规范函数命名 必要时 可用下划线间隔 示例如下 public void PrintTrackData public void ShowChar int aIndex char aszMyChar 5 25 2形参形参 所有形参的名称都应当表达出它的用途 如果合适的话 形参的名称最好以字母 a 为 前缀 例如 public void SomeProc string aUserName integer aUserAge 当参数名与类的特性或字段同名时 前缀 a 就有必要了 5 35 3常量和变量常量和变量 5 3 15 3 1 常量和宏定义常量和宏定义 常量和宏定义必须具有一定的实际意义 常量和宏定义必须全部以大写字母 中间可根 据意义的连续性用下划线连接 每一条定义的右侧必须有一简单的注释 说明其作用 资源名字定义格式 菜单 IDM XX 或者 CM XX 位图 IDB XX 对话框 IDD XX 字符串 IDS XX DLGINIT DIALOG XX ICON IDR XX 10 5 3 25 3 2 变量变量 变量命名必须具有一定的实际意义 形式为 xAbcFgh x 由变量类型确定 Abc Fgh 表示 连续意义字符串 如果连续意义字符串仅两个 可都大写 如 OK 常用的变量举例如下 以下面字母或符号作为前缀 分别具有如下意义 x y 坐标 att 表属性 c 类对象 cMain 对象实例 m 类成员变量 m nVal m bFlag s 类静态成员变量 s nVal s bFlag 5 3 2 15 3 2 1 局部变量局部变量 局部变量遵循其他变量的命名规则 通常以 n 作为前缀 局部变量中可采用如下几个通用变量 nTemp nResult I J 一般用于循环变量 5 3 2 25 3 2 2 全局变量全局变量 全局变量一般以字母 g 打头 并遵循其他变量的命名规则 5 45 4函数使用说明 接口命名 函数使用说明 接口命名 NameSpaceNameSpace 命名命名 函数使用说明包括外来函数及内部函数的使用说明 外部引用函数必须在右侧注明函 数来源 模块名及文件名 如是内部函数 只要注释 local module 即可 例如 strName GetUserName strUserId local module strName GetUserName strUserId Module Name UserManage File Name fm UserManage 缩写类型举例 dtDateTimedtText szcharszText sbsbytesbText btbytebtText nintnText uiuintuiText llonglText ululongulText ffloatfText ddoubledText bboolbText dedecimaldeText strstringstrText 11 事件函数的使用说明 public void EventHandler object sd Event e Event 表示事件响应的函数 接口命名 接口的命名一般都以 I 作为首字母 为了和类区分 例如 interface IComnunication 命名空间 命名空间命名规则从原则上和函数命名相同 通常格式如下 NameSpace 命名 N 部署位置 项目名称 namespace 名称 其他 Application 命名 P 部署位置 项目名称 5 55 5控件的命名控件的命名 C 控件规则为了和 net 类库统一 分 WindowsForm 程序和 Web 程序 下面就这两部分 分别描述 1 1 WindowsFormWindowsForm 程序程序 用小写前缀表示类别 fm 窗口 cmd 按钮 cob combo 下拉式列表框 txt 文本输入框 lab labal 标签 img image 图象 pic picture grd Grid 网格 scr 滚动条 lst 列表框 frm fram 2 2 WebWeb 程序程序 用大写前缀表示类别 Fm 窗口 Cmd 按钮 Cob combo 下拉式列表框 Txt 文本输入框 Lab labal 标签 Img image 图象 Pic picture Grd Grid 网格 Scr 滚动条 Lst 列表框 Frm fram 5 65 6类型类型 12 5 6 15 6 1 一般类型一般类型 5 6 1 15 6 1 1 枚举型枚举型 枚举类型名必须代表枚举的用途 枚举类型的标识符列表的前缀应包含 2 3 个小写 字符 来彼此关联 例如 enum SongType stRock stClassical stCountry stAlternative stHeavyMetal stRB 5 6 25 6 2 构造类型构造类型 5 6 2 15 6 2 1 数组类型数组类型 数组类型名应表达出该数组的用途 例如 string weekDays new string 7 字符串型数组 weekDays 包括 7 个元素 5 6 2 25 6 2 2 结构体类型结构体类型 结构体类型命名必须全部用大写字母 原则上前面以下划线开始 结构体变量命名必须 用大小写字母组合 第一个字母必须使用大写字母 必要时可用下划线间隔 对于私有 数据区 必须注明其所属的进程 全局数据定义只需注意其用途 示例如下 public struct DBS DATABASE char szProductName 20 char szAuthor 20 char szReleaseDate 16 char szVersion 10 unsigned long MaxTables unsigned long UsedTables DBS DATABASE GdataBase 5 6 35 6 3 类类型类类型 5 6 3 15 6 3 1 类命名与格式类命名与格式 类的名称应当表达出类的用途 一般的类名前要加字母 C 如果是接口类那么类名 前要加 I 错误异常类的类名前要加 E 而类引用类型 Class reference type 则要在类名后加 Class 抽象类一般是在类名前还要加 Abstract 5 6 3 25 6 3 2 属性命名规则属性命名规则 属性的命名遵循与变量相