嵌入式软件编程规范.doc

TRZN TRZN 嵌入式软件编程规范嵌入式软件编程规范 TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 2 of 47 文档修改历史 文档修改历史 版本号版本号日期日期修改者修改者及常用邮箱及常用邮箱修改日志修改日志 0 12016 10 28 杨科 ykee126 根据查阅的相关资料整理 此版本为第一次提交 TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 3 of 47 1文档概述文档概述 4 1 1关于本文档 4 1 2参考文献 4 2排版排版 5 3注释注释 10 4 4标识符命名标识符命名 19 5可读性可读性 25 6变量 结构变量 结构 26 7宏宏 31 8函数 过程函数 过程 33 9可测性可测性 41 10代码版本管理代码版本管理 44 10 1代码质量定义 44 10 2GIT分支定义 44 10 3GIT代码引入规定 44 10 4GIT代码 COMMIT顺序 45 10 5COMMIT文件过程中的其他注意事项 45 11附录附录 A 推荐编辑器的默认配置修改推荐编辑器的默认配置修改 46 11 1KEIL UVISION5 默认配置修改 46 TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 4 of 47 1文档概述文档概述 1 1关于本文档关于本文档 本文档规范了芜湖天人智能有限公司嵌入式软件部软件代码的书写规范和原则 本文档仅供公司内部员工使用 公司机密 严禁外传 本文档中各规则的格式如下 规则 编号 规则内容 标记 其中其中 标记标记 的含义如下 的含义如下 必须 必须 表示该条规则是必须遵守的 表示该条规则是必须遵守的 建议 建议 表示该条规则是建议遵守的 表示该条规则是建议遵守的 可选 或没有标记 可选 或没有标记 表示该条规则是可选择遵守的 表示该条规则是可选择遵守的 本文档的示例中 如有使用 并非代码注释 而是文档的注释 有可能是文档中对代码注释的解释 1 2参考文献参考文献 1 高质量 C 编程 2 Effective C 3 More Effective C 4 C Primer 5 Thinking in C TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 5 of 47 2排版排版 规则规则 2 1 程序块要采用缩进风格编写 缩进的空格数为程序块要采用缩进风格编写 缩进的空格数为4个个 对齐使用空格键 不得使用对齐使用空格键 不得使用TAB键 键 必须必须 嵌入式软件开发的代码编辑器 推荐使用 Keil uVision5 编辑器参数设置见附录 A 规则规则 2 2 相对独立的程序块之间 变量说明之后必须加空行 相对独立的程序块之间 变量说明之后必须加空行 必须必须 示例 不正确的书写方式 不正确的书写方式 if rpr valid ni ni program code gRprRepssnInd gRprSsnData idx repssn index gRprRepssnNi gRprSsnData idx ni 正确的书写方式正确的书写方式 if rpr valid ni ni program code 空行 gRprRepssnInd gRprSsnData idx repssn index gRprRepssnNi gRprSsnData idx ni 规则规则 2 3 较长的语句 较长的语句 80字符 要分成多行书写 长表达式要在低优先级操作符处划分新行 操字符 要分成多行书写 长表达式要在低优先级操作符处划分新行 操 作符放在新行之首 划分出的新行要进行适当的缩进 使排版整齐 语句可读 作符放在新行之首 划分出的新行要进行适当的缩进 使排版整齐 语句可读 必须必须 示例 gRprPermCountMsg head len RPR NO7 TO STAT PERM COUNT LEN RPR STAT SIZE PER FRAM sizeof UINT32 gSysAcbTaskTable frame id RPR STAT TASK CHECK NUMBER index nOccupied rprStatPoi index nOccupied gSysAcbTaskTable taskno nDurationTrueOrFalse SYS getSccpStatisticState statItem gRprReportOrNotFlag SYS MAX ACT TASK NUMBER taskno 规则规则 2 4 循环 判断等语句中若有较长的表达式或语句 则要进行适当的分行 长表达式要在低循环 判断等语句中若有较长的表达式或语句 则要进行适当的分行 长表达式要在低 优先级操作符处划分新行 操作符放在行尾 优先级操作符处划分新行 操作符放在行尾 必须必须 示例 TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 6 of 47 if taskno gSysMaxActTaskNumber i rprBufferKeyword wordIndex nWordLength i j program code 空行 for i 0 j 0 i rprFirstWordLength i j program code 规则规则 2 5 若函数的参数较长 则要进行适当的分行 若函数的参数较长 则要进行适当的分行 必须必须 示例 rpr n7statStrCompare UINT8 rpr n7statFlashActDuration statItem frameId SYS STAT TASK CHECK NUMBER index statObject 规则规则 2 6 不允许把多个短语句写在一行中 即一行只写一条语句 不允许把多个短语句写在一行中 即一行只写一条语句 必须必须 示例 TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 7 of 47 不正确的书写方式 不正确的书写方式 rect nLength 0 rect nWidth 0 正确的书写方式 正确的书写方式 rect nLength 0 rect nWidth 0 规则规则 2 7 if for do while case switch default等语句自占一行 且等语句自占一行 且 if for do while等语句的执行语句部分无论多少都要加括号等语句的执行语句部分无论多少都要加括号 必须必须 示例 不正确的书写方式 不正确的书写方式 if pUserCR NULL return 正确的书写方式 正确的书写方式 if NULL pUserCR return 规则规则 2 8 在比较表达式中 如果有常量 尽量把常量放在前面 在比较表达式中 如果有常量 尽量把常量放在前面 建议建议 这样 万一不小心把 误敲成 就会通不过翻译 不致引起难查的问题 规则规则 2 9 程序块的分界符 如程序块的分界符 如C C 语言的大括号语言的大括号 和和 应各独占一行并且位于同一列 应各独占一行并且位于同一列 同时与引用它们的语句左对齐 在函数体的开始 类的定义 结构的定义 枚举的定义以及同时与引用它们的语句左对齐 在函数体的开始 类的定义 结构的定义 枚举的定义以及 if for do while switch case语句中的程序都要采用如上的缩进方式 语句中的程序都要采用如上的缩进方式 建议建议 示例 本规则的特例见 2 7 的说明部分 不正确的书写方式 不正确的书写方式 for program code if program code void example fun void program code 正确的书写方式 正确的书写方式 for program code if program code void example fun void program code switch var TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 8 of 47 case OPTION1 break case OPTION2 if CONDITION 后不应加空格 后不应加空格 必须必须 说明 采用这种松散方式编写代码的目的是使代码更加清晰 由于留空格所产生的清晰性是相对的 所以 在已经非常清晰的语句中没有必要再留空格 如果语句已足够 清晰则括号内侧 即左括号后面和右括号前面 不需要加空格 多重括号间不必加空格 因为在 C C 语言 中括号已经是最清晰的标志了 在长语句中 如果需要加的空格非常多 那么应该保持整体清晰 而在局部不加空格 给操作符留空格时不 要连续留两个以上空格 示例 规则规则 2 10 1 逗号 分号只在后面加空格 int a b c 规则规则 2 10 2 比较操作符 赋值操作符 算术操作符 逻辑操作符 a 2 a b 2 规则规则 2 10 3 内容操作 与内容之间 TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 9 of 47 flag isEmpty 非操作 与内容之间 p 地址操作 与内容之间 规则规则 2 10 4 前后不加空格 p id pid 指针前后不加空格 规则规则 2 10 5 if for while switch 等与后面的括号间应加空格 使 if 等关键字更为突出 明显 if a b Param2 meaning Output If there s no parameters for output this field can be None or omitted Returns OK ERROR Description This is an external function of XXX STATUS XXX Func1 UINT8 Param1 UINT32 Param2 规则规则 3 4 1 注 使用注 使用 git 在在 commit 代码时填写充分 准确的代码时填写充分 准确的 message 必须必须 规则规则 3 5 函数头部应进行注释 列出 函数的目的函数头部应进行注释 列出 函数的目的 功能 输入参数 输出参数 返回值 调用关功能 输入参数 输出参数 返回值 调用关 系 函数 表 等 系 函数 表 等 必须必须 函数注释模板示例 TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 13 of 47 Function Name XXX ExternalFunc1 Input Param1 meaning Param2 meaning Output If there s no parameters for output this field can be None or omitted Returns OK ERROR Description Performs xxx functions Note Any special note This can be omitted 其它可选择的函数头说明 Calls 被本函数调用的函数清单 Called By 调用本函数的函数清单 Table Accessed 被访问的表 此项仅对于牵扯到数据库操作的程序 Table Updated 被修改的表 此项仅对于牵扯到数据库操作的程序 Others 其它说明 STATUS XXX ExternalFunc1 UINT8 Param1 UINT32 Param2 规则规则 3 5 1 外部函数必须有函数头注释 外部函数必须有函数头注释 必须必须 规则规则 3 5 2 内部函数强烈建议使用函数头注释 内部函数强烈建议使用函数头注释 建议建议 规则规则 3 6 边写代码边注释 修改代码同时修改相应的注释 以保证注释与代码的一致性 不再有边写代码边注释 修改代码同时修改相应的注释 以保证注释与代码的一致性 不再有 用的注释要删除 注释的格式尽量统一 用的注释要删除 注释的格式尽量统一 必须必须 示例 单行注释 Create a one shot timer from now 多行注释 One or more tables of lteDevDescr structures must also be defined for each board type into the dynamically loaded board specific configuration file The device descriptor provides function pointers that give standard line termination equipment API access to a specific hardware driver 规则规则 3 7 注释的内容要清楚 明了 含义准确 防止注释二义性 注释的内容要清楚 明了 含义准确 防止注释二义性 建议建议 说明 错误的注释不但无益反而有害 规则规则 3 8 避免在注释中使用缩写 特别是非常用缩写避免在注释中使用缩写 特别是非常用缩写 建议建议 说明 在使用缩写时或之前 应对缩写进行必要的说明 TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 14 of 47 规则规则 3 9 注释应与其描述的代码相近 对代码的注释应放在其上方或右方 对单条语句的注释 注释应与其描述的代码相近 对代码的注释应放在其上方或右方 对单条语句的注释 相邻位置 不可放在下面 相邻位置 不可放在下面 如放于上方则需与其上面的代码用空行隔开如放于上方则需与其上面的代码用空行隔开 必须必须 示例 如下例子不符合规范 例 1 错 get replicate sub system index and net indicator rprRepssnInd rprSsnData index nRepssnIndex rprRepssnNi rprSsnData index ni 例 2 错 rprRepssnInd rprSsnData index nRepssnIndex rprRepssnNi rprSsnData index ni get replicate sub system index and net indicator 应如下书写 get replicate sub system index and net indicator rprRepssnInd rprSsnData index nRepssnIndex rprRepssnNi rprSsnData index ni 规则规则 3 10 对于所有有物理含义的变量 常量 如果其命名不是充分自注释的 在声明时都必须加对于所有有物理含义的变量 常量 如果其命名不是充分自注释的 在声明时都必须加 以注释 说明其物理含义 变量 常量 宏的注释应放在其上方相邻位置或右方 以注释 说明其物理含义 变量 常量 宏的注释应放在其上方相邻位置或右方 必须必须 示例 示例 1 active statistic task number define SYS MAX ACT TASK NUMBER 1000 示例 2 define SYS MAX ACT TASK NUMBER 1000 active statistic task number 规则规则 3 11 数据结构声明数据结构声明 包括数组 结构 类 枚举等包括数组 结构 类 枚举等 如果其命名不是充分自注释的 必须加 如果其命名不是充分自注释的 必须加 以注释 对数据结构的注释应放在其上方相邻位置 不可放在下面 对结构中的每个域的注释放在此域以注释 对数据结构的注释应放在其上方相邻位置 不可放在下面 对结构中的每个域的注释放在此域 的右方 的右方 必须必须 示例 可按如下形式说明枚举 数据 联合结构 TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 15 of 47 sccp interface with sccp user primitive message name typedef enum SCP USER PRIMITIVE t SCP UNITDATA IND sccp notify sccp user unit data come SCP NOTICE IND Sccp notify user the No 7 network can not transmission this message SCP UNITDATA REQ sccp user s unit data transmission request SCP USER PRIMITIVE T 规则规则 3 12 全局变量要有较详细的注释 包括对其功能 取值范围 哪些函数或过程存取它以及存全局变量要有较详细的注释 包括对其功能 取值范围 哪些函数或过程存取它以及存 取时注意事项等的说明 取时注意事项等的说明 必须必须 示例 The ErrorCode when SCCP translate Global Title failure as follows 0 SUCCESS 1 GT Table error 2 GT error Others not used Only function SCCP Translate in this modual can modify it and other module can visit it through call the function SCCP GetGTTransErrorCode UINT8 gGTTranErrorCode 规则规则 3 13 代码中的特殊处理 或者软件改变方案 必须加注释 注明为何要这样做 代码中的特殊处理 或者软件改变方案 必须加注释 注明为何要这样做 必须必须 说明 只有加了注释 以后的维护者才有可能明白前因后果 规则规则 3 14 注释与所描述内容进行同样的缩排 注释与所描述内容进行同样的缩排 必须必须 说明 可使程序排版整齐 并方便注释的阅读与理解 示例 如下例子 不正确的布局 排版不整齐 阅读稍感不方便 不正确的不正确的布局布局 void example fun void code one comments CodeBlock One code two comments CodeBlock Two 正确的布局 正确的布局 void example fun void code one comments CodeBlock One code two comments CodeBlock Two TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 16 of 47 规则规则 3 15 将注释与其上面的代码用空行隔开 将注释与其上面的代码用空行隔开 必须必须 示例 如下例子 显得代码过于紧凑 如下例子 显得代码过于紧凑 code one comments program code one code two comments program code two 应如下书写应如下书写 code one comments program code one code two comments program code two 规则规则 3 16 对变量的定义和分支语句 条件分支 循环语句等 必须编写注释 对变量的定义和分支语句 条件分支 循环语句等 必须编写注释 建议建议 说明 这些语句往往是程序实现某一特定功能的关键 对于维护人员来说 良好的注释帮助更好的理解程序 规则规则 3 17 对于对于switch语句下的语句下的case语句 如果因为特殊情况需要处理完一个语句 如果因为特殊情况需要处理完一个case后进入下一后进入下一 个个case处理 必须在该处理 必须在该case语句处理完 下一个语句处理完 下一个case语句前语句前加上明确的注释加上明确的注释 必须必须 说明 这样比较清楚程序编写者的意图 有效防止无故遗漏 break 语句 示例 注意斜体加粗部分 case CMD UP ProcessUp break case CMD DOWN ProcessDown break case CMD FWD ProcessFwd ProcessCFW B ProcessCFW B nownow jumpjump intointo casecase CMD ACMD A case CMD A ProcessA break case CMD B ProcessB break default break TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 17 of 47 规则规则 3 3 1818 避免在一行代码或表达式的中间插入注释 避免在一行代码或表达式的中间插入注释 必须必须 说明 除非必要 如 PC LINT 的行禁止检查标记 不应在代码或表达中间插入注释 否则容易使代码可 理解性变差 规则规则 3 3 1919 通过对函数或过程 变量 结构等正确的命名以及合理地组织代码的结构 使代码成为通过对函数或过程 变量 结构等正确的命名以及合理地组织代码的结构 使代码成为 自注释的 自注释的 建议建议 说明 清晰准确的函数 变量等的命名 可增加代码可读性 并减少不必要的注释 规则规则 3 3 2020 代码的功能 意图层次上进行注释 提供有用 额外的信息 代码的功能 意图层次上进行注释 提供有用 额外的信息 建议建议 说明 注释的目的是解释代码的目的 功能和采用的方法 提供代码以外的信息 帮助读者理解代码 防止 没必要的重复注释信息 示例 如下注释意义不大 if receive flag is TRUE if receive flag 而如下的注释则给出了额外有用的信息 if mtp receive a message from links if receive flag 规则规则 3 3 2121 在程序块的结束行右方加注释标记 以表明某程序块的结束 在程序块的结束行右方加注释标记 以表明某程序块的结束 可选可选 说明 当代码段较长 特别是多重嵌套时 这样做可以使代码更清晰 更便于阅读 在 Source Insight 软件 中可以自动显示这类信息 示例 参见如下例子 if flag program code while index MAX INDEX program code end of while index MAX INDEX 指明该条 while 语句结束 end of if flag 指明是哪条 if 语句结束 TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 18 of 47 规则规则 3 3 2222 注释应考虑程序易读及外观排版的因素 嵌入式软件的注释必须全部使用英文 注释应考虑程序易读及外观排版的因素 嵌入式软件的注释必须全部使用英文 建议建议 TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 19 of 47 4 4标识符命名标识符命名 规则规则 4 4 1 1 标识符的命名要清晰 明了 有明确含义 同时使用完整的单词或大家基本可以理解的缩标识符的命名要清晰 明了 有明确含义 同时使用完整的单词或大家基本可以理解的缩 写 避免使人产生误解 写 避免使人产生误解 建议建议 说明 较短的单词可通过去掉 元音 形成缩写 较长的单词可取单词的头几个字母形成缩写 一些单词有 大家公认的缩写 示例 如下单词的缩写能够被大家基本认可 temp 可缩写为 tmp flag 可缩写为 flg statistic 可缩写为 stat increment 可缩写为 inc decrease 可缩写为 dec message 可缩写为 msg reserve 可缩写为 resv receive 可缩写为 rec 规则规则 4 4 2 2 命名中若使用特殊约定或缩写 则要有注释说明 命名中若使用特殊约定或缩写 则要有注释说明 必须必须 说明 应该在源文件的开始之处 对文件中所使用的缩写或约定 特别是特殊的缩写 进行必要的注释说明 规则规则 4 4 3 3 自己特有的命名风格 要自始至终保持一致 不可来回变化 自己特有的命名风格 要自始至终保持一致 不可来回变化 建议建议 说明 个人的命名风格 在符合所在项目组或产品组的命名规则的前提下 才可使用 即命名规则中没有 规定到的地方才可有个人命名风格 规则规则 4 4 4 4 常量的定义全部采用大写单词 单词中间以下划线分开 并且各模块中的常量第一个单词常量的定义全部采用大写单词 单词中间以下划线分开 并且各模块中的常量第一个单词 必须为模块头 定义的常数必须加括号 必须为模块头 定义的常数必须加括号 必须必须 示例 defineRPR STATUS CALLBACK 1 define RPR RET ERR CODE NULL 2 规则规则 4 4 5 5 结构的命名必须全部为大写字母 第结构的命名必须全部为大写字母 第1 1个单词为模块名 最后一个单词为个单词为模块名 最后一个单词为 T T 单词之间 单词之间 以下划线分开 以下划线分开 必须必须 TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 20 of 47 说明 示例 typedef struct RVP MSG HDR t UINT32 version 4 UINT32 resvd 16 UINT32 msgLen the over all length of the message excluding the header RVP MSG HDR T typedef struct RVP RESV MSG t RVP MSG HDR T msgHdr UINT8 ucSvcNum UINT8 ucSvcCode UINT16 usSvcLen UINT32 unSvcData1 UINT32 unSvcData2 UINT32 unSvcData3 RVP RESV MSG T 规则规则 4 4 6 6 枚举类型的命名必须全部为大写字母 第枚举类型的命名必须全部为大写字母 第1 1个单词为模块名 最后一个单词为个单词为模块名 最后一个单词为 T T 单词 单词 之间以下划线分开 之间以下划线分开 必须必须 示例 typedef enum The Instance State Definition PLB INST ERROR 2 PLB INST DEINIT 1 PLB INST DEACTIVE 0 PLB INST INIT PLB INST STANDBY PLB INST ACTIVE PLB INST STATE T 规则规则 4 4 7 7 对于变量命名 禁止取单个字符 如对于变量命名 禁止取单个字符 如i i j j k k 建议除了要有具体含义外 还能表明 建议除了要有具体含义外 还能表明 其变量类型 数据类型等 但其变量类型 数据类型等 但i i j j k k作局部循环变量是允许的 作局部循环变量是允许的 必须必须 规则规则 4 4 8 8 变量名中的大小写与分隔 使用单词首字母大写作为变量中各单词的间隔 变量的打头字变量名中的大小写与分隔 使用单词首字母大写作为变量中各单词的间隔 变量的打头字 母 打头单词必须小写 禁止使用下划线母 打头单词必须小写 禁止使用下划线 做变量中的分割符 做变量中的分割符 必须必须 例如 UINT32 dccResetAddr STATUS rprInstStatus TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 21 of 47 规则规则 4 4 9 9 全局变量的头部必须有全局变量的头部必须有 g subsystemg subsystem 的标记 用于区分全局变量的模块范围 同时防止的标记 用于区分全局变量的模块范围 同时防止 重名 相同模块内的全局变量必须尽量放在同一个文件中 重名 相同模块内的全局变量必须尽量放在同一个文件中 必须必须 例如 UINT8 gFmaVariableName char gsRprModuleName RPR MAX STRING LEN 规则规则 4 10 1 模块的全局变量必须组织在同一个结构体中进行管理 模块的全局变量必须组织在同一个结构体中进行管理 必须必须 例如 STP 模块中的全局变量定义如下 typedef struct MIBpbRstpBridgeTable t stp gBridgeCfg MIBpbRstpPortTable t stp gPortCfg HII MAX PORT NUM stp BridgeData s stp gBridgeInfo stp PortData s stp gPortInfo HII MAX PORT NUM stp StateMachine s stp gPortSM HII MAX PORT NUM stp BPDU s stp gRcvdBPDU HII MAX PORT NUM int stp gTimerOneSecond STP S STPInfo T 在 stp config c 中采用该结构定义的变量如下 STP S STPInfo T stp gGvar HII MAX INSTANCE NUM 规则规则 4 4 1111 变量的前缀表示方法变量的前缀表示方法 必须必须 类型类型描述描述前缀前缀举例举例 指针 pUINT8 pucIndex 定长数组 a optional UINT8 aMyVar MAX LEN BOOL布尔值 bBOOL bMonitored char 字符串 schar sTtiTx 64 UINT88 bit 无符号整数uc optional UINT8 ucIndex or UINT8 index UINT1616 bit 无符号整数us optional UINT16 usPort or UINT16 port UINT3232 bit 无符号整数ul optional UINT32 ulErrorCode char可显示字符c optional char cHexHigher4Bits cHexLower4Bits int依赖于操作系统的不定长整数 不建议使用 n optnional int nIndex or int j UINT依赖于操作系统的不定长无符 号整数 不建议使用 u optional Enum枚举e optional other 其他复杂类型 如结构 按惯例或自行定义 注意全局一致 MSG Q ID msgQPmon TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 22 of 47 Table 1 变量的前缀变量的前缀 说明 变量的前缀可以由各中前缀组合表示 变量的命名来自参考文献 1 例如 BOOL gbPslEnabled UINT32 gpulHandle 规则规则 4 4 1212 通用类型定义的使用 尽可能使用通用类型定义的使用 尽可能使用CTD CommonCTD Common TypeType Definitions Definitions 中定义的数值类型 中定义的数值类型 尽量少定义自己的数据类型尽量少定义自己的数据类型 在不影响程序可读性的前提下在不影响程序可读性的前提下 必须必须 CTD 包括以下定义 通用的常量和类型定义 如 UINT8 UINT16 UINT32 与 SDH 有关的通用常量和类型定义 通用错误返回码 PB ERROR CODE T 规则规则 4 4 1313 除非必要 不要用数字或较奇怪的字符来定义标识符 除非必要 不要用数字或较奇怪的字符来定义标识符 示例 如下命名 使人产生疑惑 define RPR 0 TEST define RPR 1 TEST void set sls00 UINT8 sls 应改为有意义的单词命名 define RPR EXAMPLE UNIT TEST define RPR EXAMPLE ASSERT TEST void RPR setUdtMsgSls UINT8 ucSls 规则规则 4 4 1414 用正确的反义词组命名具有互斥意义的一组变量或相反动作的一组函数等 不得把意义用正确的反义词组命名具有互斥意义的一组变量或相反动作的一组函数等 不得把意义 相反的单词合并在一个变量名或函数名中 以免意义不清 相反的单词合并在一个变量名或函数名中 以免意义不清 建议建议 说明 下面是一些在软件中常用的反义词组 add remove begin end create destroy insert delete first last get release increment decrement put get add delete lock unlock open close min max old new start stop next previous source target show hide send receive source destination TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 23 of 47 cut paste up down 示例 int minSum int maxSum int addUser UINT8 userName int deleteUser UINT8 userName 错误 int addOrDelUser UINT8 userName 规则规则 4 4 1515 模块必须全部采用模块必须全部采用3 3个字符 模块的目录个字符 模块的目录3 3个字符必须全部大写个字符必须全部大写 其中第一个字符不得为数其中第一个字符不得为数 字字 模块下至少有两个子目录 分别为小写的 模块下至少有两个子目录 分别为小写的 incinc 和和 srcsrc 必须必须 项目目录树模板 项目目录树模板 SOURCE ROOT include infra ZZZ appl XXX inc exported functions and definitions src source code and private header files doc documents test plans YYY inc src doc 其中 ZZZ XXX YYY 为模块名 规则规则 4 4 1616 模块的外部接口定义应当放在模块的外部接口定义应当放在 XXX incXXX inc 目录下 建议把所有接口放在一个文件中 此时目录下 建议把所有接口放在一个文件中 此时 一般可命名为一般可命名为 xxx ei hxxx ei h 必须必须 TRZN 项目 项目 Embedded software development 领域领域 SW Engineering 文件文件名称名称 嵌入式软件编程规范嵌入式软件编程规范 文件号文件号 SW 00 00 0001 版本号版本号 0 1 日期日期 2016 10 28 所属所属部门部门 电控质量管理部电控质量管理部 仅限项目组内部传阅仅限项目组内部传阅 Page 24 of 47 规则规则 4 4 1717 模块的源文件和内部接口定义应当放在模块的源文件和内部接口定义应当放在 XXX srcXXX src 目录下 不得把内部接口与外部接口放目录下 不得把内部接口与外部接口放 在同一个头文件中 在同一个头文件中 必须必须 注意 并不是所有的头文件都放在 XXX inc 目录下 只有外部接口才是 如果文件过多 可以考虑在模块中增加 一个子目录 如 XXX def 用于存放所有定义内部接口的头文件 规则规则 4 4 1818 模块的属主模块的属主 owner owner 每个模块都有一个唯一的属主 每个模块都有一个唯一的属主 必须必须 模块属主的完整列表在 module txt 中 见下一条 规则 4 18 1 模块的属主对此模块负责 只有他可以对此模块进行修改 其他工程师不得修改此模块 除模块的属主对此模块负责 只有他可以对此模块进行修改 其他工程师不得修改此模块 除 非事先得到属主的批准 并且事后由属主审查 非事先得到属主的批准 并且事后由属主审查 规则规则 4 4 1919 在使用在使用SVSSVS时