《编程规范与原则》由会员分享，可在线阅读，更多相关《编程规范与原则（23页珍藏版）》请在金锄头文库上搜索。
1、 编程规范与原则 目标 正确 易被修改 星网锐捷通讯技术有限公司 版权所有 不得复制 作者 陈学芹 chenxq star 0 文档历史文档历史 版本号版本号 修订时间修订时间 修订备注修订备注 0 3 2005 07 14 1 根据部门人员的讨论意见 增加 必须 和 推荐 两个等级 2 对于 推荐 等级的条款 增加角注 3 增加 术语 章 0 2 2005 06 27 补充完成宏 可测性 质量保证 3 个章节 0 1 2005 06 10 编码规范与惯例初稿 1 导言导言 为何需要编程规范为何需要编程规范 之所以编程规范与惯例对于程序员来说重要 有以下几点原因 编码是程序员的职责 一个好的信
2、息技术产品必然有高质量的代码 高质量的代码首先一 点它必须遵守某种编程规范 一个软件整个生命周期内成本的 80 用于维护 几乎没有 1 个软件在整个生命周期内全部由它的原始作者来维护 编程规范改善了软件的可读性 使工程师更加快速 彻底的理解新代码 如果你的源代码被作为产品发布 那么你必须保证它和其它产品一样很好的包装并保持整 洁 大量数据表明 软件存在问题或者隐患 很大一部分是由于未遵守基本准则所致 如果能在 项目早期明确规则 则会避免许多麻烦 为了简化工作 每一个编写软件的人都必须遵守编程规范 每个人 适用范围适用范围 本文阐述的编码规范主要使用在具备下面特性的软件 以 C C 为编程语言
3、资源受限的系统 对性能有较严格要求的 如 CPU 主频较低 RAM ROM 空间较小 外围存 储空间有限 FLASH EEPROM 执行等级执行等级 本规范中每一条款都有一个执行等级 分为 必须必须 代码无条件的满足必须等级的条款 不满足的代码必须得到修改 以满足相关的条款 推荐推荐 条款非强制执行的 一般情况下遵照条款有助于改善代码的质量 若不特别指出 所有条款执行 必须 等级 2 基本原则基本原则 本规范的基本目的是提高代码的可维护性 也就说 代码必须是可读的 易于理解的 可测试的和可 移植的 2 1 所有的代码必须符合业界标准 尽可能使用标准函数库 如 ANSI C 所有的函数原型必须符
4、合 ANSI 标准 所有的参数定义必须在圆括号中定义 2 2 保持代码简单直观 避免使用深度超过 3 层以上的嵌套语句 避免编程语言中隐含或者晦涩的特性 直接表达你的意图 2 3 应用模型中不变的与可变的部分应该注意区分 让代码具备易于修改 1 2 4 保持一致 尽可能使用相同的规则 2 5 避免复杂语句 包含多个分支的语句很难被理解与测试 2 6 尽量避免使用 GOTO 2 7 请及时更新旧代码 受产品的资金 时间 范围的约束 你可能写出能工作但结构不优美 执行效率不高的代码 这情有 可原 但不要对这种代码置之不管 2 8 保持良好的软件结构 一般情况下 好的软件结构具备如下特征 顶层函数的
5、扇出较高 中层函数的扇出较少 底层函数则扇入到公共模块中 1 区分变与不变是软件分析与设计的灵魂 表现为许多种形式 如接口与实现的分离 2 9 预留调试接口 对可能存在的错误作出预防 2 10 秉持标准的灵魂 在你需要做出决策并没有直接标准的时候 你必须坚持标准的精神 3 文件命名与组织文件命名与组织 3 1 文件命名文件命名 代码文件使用下列扩展名 文件类型 扩展名 C 源文件 c C 源文件 cpp cxx C C 头文件 h 3 1 常用文件名常用文件名 文件名称文件名称 用途用途 Makefile Makefile 的首选名称 RELEASE 程序发行说明 描述各个版本的主要更改 问题
6、解决状况 尚未解决的问 题等等 首选文件名 README 总结项目目录的内容 ChangeLog 代码修改记录 详细描述对每个源文件所做的修改 最好精确到函数级 别 结构上 可采用如下形式 ChangeLog 日更改记录 文件修改记录 3 2 工程组织结构工程组织结构 为了让开发人员理解和维护上的方便 一般 嵌入式设备软件工程目录的组织结构推荐使用下列 组织形式 Project src lib include doc README ChangeLog RELEASE 其它工程文件如 IDE 相关的项目配置文件 Makefile 4 代码结构代码结构 4 1 文件头文件头 文件头是嵌入在 C C
7、 头文件或源文件中 在文件首部的注释块 一般包含如下信息 公司或组织的名称 地址 版权说明 开发人员 模块目的 功能 文件版本 修改日志 4 2 C C 头文件头文件 头文件的布局 文件头2 版本历史 常量定义 全局宏定义 2 推荐 推荐 是否在头文件包含文件头 这有些争议 有些头文件较简单 可不必包含文件头 但一般说来 公共头文件 接口 原型 需要带有文件头 全局数据类型定义 全局变量定义 外部引用定义 全局函数原型定义 4 3 C C 源文件源文件 源文件也即实现文件 其布局 文件头 版本历史 include 区 define 区 宏定义区 Macros 本地数据类型定义区 Local d
8、ata types 本地变量区 Local variables 本地表 Local tables 本地函数原型 Local function prototypes 全局函数 Global functions 局部函数 Local functions 5 排版排版 5 1 代码行宽度 推荐每行的代码宽度限制在 80 个字符内 80 个字符限制是由于旧显示器的约束 可视范围只有 80 个字符 较长的语句 80 字符 要分成多行书写 长表达式要在低优先级操作符处划分新行 操作符放在新行之首 划分出的新行要进行适当的缩进 使排版整齐 语句可读 5 2 TAB 字符的使用3 不应使用 TAB 字符 AS
9、CII 编码 0 x09 使用空格字符 ASCII 0 x20 实现缩进 TAB 字符在不同的计算机 打印机上表现各异 对其限制使用 可使缩进空间很好的被保持 5 3 函数 结构 循环 判断等语句都需要采用缩进 缩进请使用 4 个空格 缩进代码包含 4 个空格 ASCII 编码 0 x09 5 4 相对独立的程序块之间 变量说明之后必须加空行 示例 如下例子不符合规范 3 推荐 推荐 有些编辑器会自动使用 TAB 缩进 TAB 与空格缩进不允许同时使用 void function1 int var1 var2 var1 1 var2 2 正确的书写方法是 void function1 int
10、var1 var2 var1 1 var2 2 5 5 不允许把多个短语句写在一行中 即一行只写一条语句 示例 如下例子不符合规范 rect length 0 rect width 0 应如下书写 rect length 0 rect width 0 5 6 在两个以上的关键字 变量 常量进行对等操作时 它们之间的操作符之前 之后或者前 后要加空格 进行非对等操作时 如果是关系密切的立即操作符 如 后不应加空格 示例 1 逗号 分号只在后面加空格 int a b c 2 比较操作符 赋值操作符 算术操作符 逻辑操作符 a 2 a b 2 3 内容操作 与内容之间 flag isEmpty 非操
11、作 与内容之间 p 地址操作 与内容之间 4 前后不加空格 p id pid 指针前后不加空格 5 if for while switch 等与后面的括号间应加空格 使 if 等关键字更为突出 明显 if a b DispDigMsk 0 x80 DispScale 1 25 6 注释注释 6 1 每 1 个注释都必须有用 6 2 对于函数要给出必要的注释 列出 函数的名称 功能 入口参数 出口参数 返回值 调 用说明 除非有把握使用英语明确表达你的用意 一般情况下使用中文 sample func summary this function param1 description of para
12、m1 param2 description of param2 Detail descript the usuage of sample func Oh yeah oh my god oh my god oh my god oh yeah oh yeah oh yeah int sample func int param1 int param2 6 3 边写代码边注释 修改代码同时修改相应的注释 以保证注释与代码的一致性 不再有用 的注释要删除 6 4 尽可能使用尾部注释 示例 void ClkUpdateTime void if ClkSec CLK MAX SEC Update the s
13、econds ClkSec 0 if ClkMin CLK MAX MIN Update the minutes ClkMin 0 if ClkHour CLK MAX HOURS Update the hours ClkHour 0 else ClkHour else ClkMin else ClkSec 6 5 对于块代码的注释使用 if 0 和 endif 条件编译指令 注释不应该嵌套 要注释大段的代码 请使用 if 0 和 endif 示例 if 0 Comments out the following code define DISP TBL SIZE 5 Size of displ
14、ay buffer table define DISP MAX X 80 Max number of characters in X axis define DISP MAX Y 25 Max number of characters in Y axis define DISP MASK 0 x5F endif 6 6 在代码的功能 意图层次上进行注释 提供有用 额外的信息 6 7 注释的格式尽量统一 建议使用 6 8 将注释与其上面的代码用空行隔开 示例如下 code block one comment code block one code block two comment code b
15、lock two 7 标识符命名约定标识符命名约定 7 1 一般约定 define constants define macros typedefs enum tags 所有字符都必须大写 单词用下划线隔开 也就是 例如 DISP BUF SIZE MIN MAX etc 局部变量 也就是函数范围的 所有字符都必须小写 单词用下划线隔开 也就是 使用标准名字 例如 i j k 作循环计数器 p 做指针 文件范围变量 以模块名称为前缀 使用下划线分开 将单词的首字母大写 隔开 申明为 static 例如 Disp Buf Comm Ch 等等 全局变量 以模块名称为前缀 将单词的首字母大写 隔开
16、 示例 DispMapTbl CommErrCtr etc 局部函数 以模块名称为前缀 用下划线连接 不同单词间首字母大写 申明为 static 示例 static void Comm Putchar 全局函数 接口函数 以模块名称为前缀 不同单词间首字母大写 示例 void CommInit 7 2 保持首字母缩写 单词缩写 助记符号一致 必须创建一套首字母缩写 单词缩写 助记符号的标准 它应适合所有人使用与采纳的 下面有 1 张不完全列表 7 3 使用 module obj operation 的命名范式 定义全局常量 变量 函数的名称时 先指定模块名 或子系统名 紧接着对象名称 最后是操作名 称 如下所示 OSSemPost OSSemPend 等等 首字母缩写首字母缩写 单词缩写单词缩写 助记符号字典助记符号字典 描述描述 首字母缩写首字母缩写 单词缩写单词缩写 助记符号助记符号 Argument Arg Buffer Buf Clear Clr Clock Clk Compare Cmp Configuration Cfg Context Ctx Control Ctl De
