某为内部软件编程规范总则

---

1. 总则

某为内部软件编程规范总则围绕排版、注释、标识符命名、可读性、变量与结构、函数与过程、可测性、程序效率、质量保证、代码编辑编译审查、代码测试维护、宏12大核心领域制定规范，明确排版需4空格缩进、一行仅一条语句，注释有效量需≥20% 且头文件/源文件/函数需包含版权、功能、修改日志等指定信息，标识符命名需清晰无歧义（局部循环变量外禁单字符），函数需单一功能且扇出≤7，同时通过“正确性＞稳定性＞可测性”的质量优先原则、断言提升可测性、循环优化提高效率，最终确保代码规范、可读、可维护且适配多场景需求。

---

2. 思维导图（mindmap）

---

3. 详细总结

1. 排版（核心为“整齐、可读、无歧义”）

规则编号	核心要求	关键细节/示例
1-1	缩进风格	4个空格，开发工具自动生成代码可例外
1-2	空行要求	独立程序块之间、变量说明后必须加空行
1-3	长语句拆分	＞80字符拆分，低优先级操作符（如+、&&）处断行，操作符放新行首
1-6	单行语句	一行仅1条语句，如rect.length=0;与rect.width=0;分两行
1-7	关键字排版	if/for等独占行，执行部分必加{}，如if(p==NULL){return;}
1-8	对齐方式	仅用空格键，禁用TAB键（避免编辑器差异）
1-10	分界符对齐	{/}各独占一行、同一列，与引用语句左对齐

2. 注释（核心为“足量、准确、同步”）

• 注释量要求：源程序有效注释≥20%，避免过多或过少，注释需准确无歧义。

• 头部注释规范：

  • 头文件（.h）/说明性文件（.inc/.def）：含版权说明、版本号、生成日期、作者、内容/功能、与其他文件关系、修改日志，及函数功能简要说明。
  • 源文件：含版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及功能、修改日志（每条记录含日期、修改者、内容）。

• 函数注释规范：需包含函数目的/功能、输入参数（作用+取值+关系）、输出参数、返回值、调用关系（被调用函数/调用本函数的函数）、访问/修改的数据库表（若涉及）。

• 其他规则：边写代码边注释，修改代码同步改注释；变量/结构/全局变量需加注释说明物理含义；switch-case跳转需加注释说明意图。

3. 标识符命名（核心为“清晰、统一、无歧义”）

• 命名原则：使用完整单词或公认缩写（如temp→tmp、message→msg），避免误解；特殊缩写需在源文件开头注释说明。

• 风格统一：

  • 符合系统风格（如UNIX全小写加下划线、大小写混排），禁止Add_User这类大小写+下划线混排；
  • 允许m_AddUser（成员变量）、g_AddUser（全局变量）这类带前缀的混排。

• 禁忌规则：

  • 禁止单个字符（如i/j）作为变量名（局部循环变量除外）；
  • 避免用数字或奇怪字符（如_EXAMPLE_0_TEST_应改为_EXAMPLE_UNIT_TEST_）；
  • 除编译开关/头文件外，禁止_XXX_格式命名。

• 优化技巧：用反义词组命名互斥变量或相反动作函数（如min_sum/max_sum、add_user/delete_user）。

4. 可读性（核心为“降低理解成本”）

• 优先级明确：用括号明确表达式操作顺序，如(a|b)&&(a&c)而非a|b&&a&c，避免依赖默认优先级。
• 数字替代：含物理意义的常量用枚举/宏替代，如#define TRUNK_IDLE 0、#define TRUNK_BUSY 1，而非直接写0/1。
• 代码组织：关系紧密的代码需相邻（如rect.length=10;与rect.width=5;相邻）；避免高技巧语句（如*stat_poi+++=1;拆为*stat_poi+=1;stat_poi++;）。

5. 变量与结构（核心为“低耦合、可移植、无风险”）

• 变量规则：

  • 减少不必要公共变量（降低模块耦合），明确公共变量的含义、取值范围及存取函数；
  • 防止局部变量与公共变量重名；严禁使用未初始化变量作为右值（如C/C++未赋值指针）。

• 结构规则：

  • 功能单一（仅描述一种事务，如PERSON_STRU与TEACHER_STRU分开）；
  • 元素个数适中，过多时拆分子结构（如PERSON_STRU拆为PERSON_BASE_INFO（姓名/年龄）和PERSON_ADDRESS（地址/电话））；
  • 考虑向前兼容（预留升级空间），跨CPU通信需注意字节顺序、位域、字节对齐（如Intel与68360 CPU位域存储顺序相反）。

6. 函数与过程（核心为“可重入、单一功能、易维护”）

核心要求	具体规则	关键数字/示例
可重入性	局部变量用auto/寄存器变量，禁static；全局变量需信号量保护	-
单一功能	一个函数仅做一件事，拆多用途函数（如add_sub拆为add/sub）	规模≤200行（不含注释/空格）
参数处理	检查输入/非输入（如数据文件）有效性；项目组明确参数合法性检查责任	避多参数，禁控制参数
调用效率	设计高扇入、合理扇出的函数	扇出＜7（调度函数除外），合理扇出3-5
命名与返回值	动宾词组命名（如print_record）；明确错误返回码含义	避免process/handle等无意义动词

7. 可测性（核心为“便于测试、快速定位问题”）

• 调测工具：项目组统一调测开关及打印函数，信息格式含模块名+行号。

• 断言使用：

  • 用断言检查程序正常运行时不应发生的非法情况（如指针非空：EXAM_ASSERT(str!=NULL)）；
  • 禁止用断言检查必处理错误（如消息合理性检查需用防错程序）；正式版关闭断言。

• 测试准备：单元测试选择测试点，构造边界值/极端用例；集成测试前优化用例。

8. 程序效率（核心为“全局优先、优化关键环节”）

• 优化方向：

  • 全局效率优先于局部效率，通过改进数据结构/算法提升空间效率（如STUDENT_SCORE_STRU拆为STUDENT和STUDENT_SCORE减少重复存储）；
  • 循环优化：体内工作量最小化（如back_sum=sum;放循环外），多重循环忙循环放内层，避循环内判断（如if(data_type)放循环外）；
  • 计算优化：用乘法替代浮点除法（如radius=circle_length*PAI_RECIPROCAL/2而非circle_length/(2*PAI)）。

9. 质量保证（核心为“正确性优先，规避风险”）

• 质量优先原则（按优先级排序）：

  • 优先级	质量维度	核心要求
    1	正确性	实现设计功能
    2	稳定性、安全性	稳定可靠，无内存泄漏/越界
    3	可测性	便于测试，快速定位问题
    4	规范/可读性	符合规范，易读易理解
    5	全局效率	系统整体效率
    6	局部效率	模块/函数效率
    7	个人表达方式	开发习惯（最低优先级）

• 风险规避：

  • 资源管理：申请内存/文件句柄必释放，防引用已释放内存；
  • 代码安全：防内存越界（如usr_login_flg[usr_no-1]），检查易混淆操作符（=与==、&与&&）；
  • 分支完整性：if尽量加else，switch必有default。

10. 代码编辑、编译、审查

• 编译规则：打开所有编译器告警开关，项目组统一编译开关选项。

• 审查方式：

  • 代码走读：检查编程风格（缩进/注释）、易出错内容（未初始化变量），自审或交叉审核；
  • 代码审查：检查功能、稳定性、安全性，自审、交叉审核或抽查；测试前需代码抽查。

• 工具辅助：用PC-Lint（C语言）、LogiSCOPE等工具检查代码。

11. 代码测试、维护

• 测试要求：单元测试至少达语句覆盖，跟踪语句数据流；测试边界情况及出错处理代码。

• 维护规则：

  • 错误处理：发现错误立即修改并记录，分析自动消失的错误原因；
  • 版本管理：用工具维护版本，升级必测，正式版修改需文档记录；
  • 代码优化：清理后需审查测试，去除代码随机性（如无用数据），使结果可预测。

12. 宏（核心为“无歧义、无副作用”）

• 表达式括号：宏定义表达式需加完备括号，如#define RECTANGLE_AREA(a,b) ((a)*(b))（避免优先级问题）。
• 多语句包裹：多条表达式用大括号包裹，如#define INTI_RECT(a,b) {a=0;b=0;}（避免仅执行第一条）。
• 参数不变：禁用变化参数，如SQUARE(a++)会导致a执行两次++，需改为SQUARE(a);a++;。

---

4. 关键问题

问题1：编程规范中，“排版”环节对“长语句拆分”和“分界符对齐”有明确要求，具体规则是什么？这些规则如何提升代码可读性？

答案： 

• 长语句拆分规则：长度＞80字符的语句需拆分，长表达式在低优先级操作符（如+、&&、==）处断行，操作符置于新行首并适当缩进（如perm_count_msg.head.len = NO7_TO_STAT_PERM_COUNT_LEN + STAT_SIZE_PER_FRAM * sizeof(_UL);拆分为两行，+放新行首）。 
• 分界符对齐规则：程序块分界符（{、}）各独占一行，且位于同一列，与引用它们的语句左对齐（如for(...) { ... }需改为for(...) {换行、代码缩进、}单独成行并与for对齐）。 
• 可读性提升逻辑：长语句拆分避免横向滚动查看，低优先级操作符断行符合人类阅读逻辑（先理解低优先级运算关系）；分界符对齐明确代码块边界，尤其多重嵌套时（如if嵌套while），可快速定位块的开始与结束，减少理解成本。

问题2：编程规范要求函数需具备“可重入性”，具体实现规则是什么？为何多任务环境下“可重入性”对软件稳定性至关重要？

答案： 

• 可重入性实现规则：① 局部变量使用auto（缺省）或寄存器变量，禁止使用static局部变量（static变量存于数据区，多进程调用会共享状态，导致结果不可预测）；② 若函数需使用全局变量，必须通过关中断、信号量（P/V操作） 保护全局变量（防止多进程同时修改，导致变量状态异常）。 
• 多任务环境下的重要性：多任务系统中，同一函数可能被多个进程并发调用。若函数不可重入（如用static局部变量），会出现“进程A修改变量后，进程B中断并覆盖变量，进程A恢复后使用错误值”的问题，导致逻辑错误或系统崩溃；而可重入函数通过隔离局部状态、保护全局资源，确保多进程调用时结果一致，是软件稳定性的核心保障。