编程规范简约版

1.       排版

 

1-1：程序块要采用缩进风格编写，缩进的空格数为4个。

1-2：布尔类型的比较，必须采用等于==、不等于!=和 SK_TRUE、SK_FALSE 比较。

1-3：不允许使用函数的返回值直接==、!=、>、<、>=、<=比较，应该采用先赋值给变量，再和该变量比较的方式。

1-4：相对独立的程序块之间、变量说明之后必须加空行。

1-5：较长的语句（>80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。

1-6：不允许把多个短语句写在一行中，即一行只写一条语句。

1-7：i表达式中有等于 ==、不等于 != 的比较时，需要将常量放在左边。

1-8：if、for、do、while、case、switch、default等语句自占一行，且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。

1-9：对齐只使用空格键，不使用TAB键。

1-10：函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case语句下的情况处理语句也要遵从语句缩进要求。

1-11：程序块的分界符（如C/C++语言的大括号‘{’和‘}’）应各独占一行并且位于同一列，同时与引用它们的语句左对齐。在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。

1-12：在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如－>），后不应加空格。

 

2.       注释

 

1.       数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的右方。

2.       全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。

3.       对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。

4.       边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。

5.  注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。

6.  注释与所描述内容进行同样的缩排。

7.  将注释与其上面的代码用空行隔开。

8.  在程序块的结束行右方加注释标记，以表明某程序块的结束。

9.  注释格式尽量统一，建议使用“/* …… */”。

 

 

 

 

3.    标识符命名

标识符的命名要清晰、明了，有明确含义，自己特有的命名风格，要自始至终保持一致，不可来回变化。在同一软件产品内，应规划好接口部分标识符（变量、结构、函数及常量）的命名，防止编译、链接时产生冲突。用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。

 

4.    可读性

1.       注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。

2.       避免使用不易理解的数字，用有意义的标识来替代。

3.       源程序中关系较为紧密的代码应尽可能相邻。

4.       不要使用难懂的技巧性很高的语句，除非很有必要时。

 

5．变量、结构

1. 严禁使用未经初始化的变量作为右值。

2. 仔细定义并明确公共变量的含义、作用、取值范围及公共变量间的关系。

3. 当向公共变量传递数据时，要十分小心，防止赋与不合理的值或越界等现象发生。

4. 按照既定的命名规则命名，防止局部变量与公共变量同名。

5. 构造仅有一个模块或函数可以修改、创建，而其余有关模块或函数只访问的公共变量，防止多个不同模块或函数都可以修改、创建同一公共变量的现象。

6．结构的功能要单一，是针对一种事务的抽象。

7. 结构中元素的个数应适中。若结构中元素个数过多可考虑依据某种原则把元素组成不同的子结构，以减少原结构中元素的个数。

8.       仔细设计结构中元素的布局与排列顺序，使结构容易理解、节省占用空间，并减少引起误用现象。

9. 结构的设计要尽量考虑向前兼容和以后的版本升级，并为某些未来可能的应用保留余地（如预留一些空间等）。

10. 编程时，要注意数据类型的强制转换。

11. 对编译系统默认的数据类型转换，也要有充分的认识。

12. 对自定义数据类型进行恰当命名，使它成为自描述性的，以提高代码可读性。注意其命名方式在同一产品中的统一。

 

6. 函数、过程

1. 对所调用函数的错误返回码要仔细、全面地处理。

2. 明确函数功能，精确（而不是近似）地实现函数设计。

3. 编写可重入函数时，应注意局部变量的使用。

4．编写可重入函数时，若使用全局变量，则应通过关中断、信号量（即P、V操作）等手段对其加以保护。

5. 在同一项目组应明确规定对接口函数参数的合法性检查应由函数的调用者负责还是由接口函数本身负责，缺省是由函数调用者负责。

6. 防止将函数的参数作为工作变量。

7. 函数的规模尽量限制在200行以内。

8. 一个函数仅完成一件功能。

9. 函数的功能应该是可以预测的，也就是只要输入数据相同就应产生同样的输出。

10. 避免设计多参数函数，不使用的参数从接口中去掉。

11. 非调度函数应减少或防止控制参数，尽量只使用数据参数。

12. 检查函数所有非参数输入的有效性，如数据文件、公共变量等。

13. 使用动宾词组为执行某操作的函数命名。如果是OOP方法，可以只有动词（名词是对象本身）。

14. 避免使用无意义或含义不清的动词为函数命名。

15. 函数的返回值要清楚、明了，让使用者不容易忽视错误情况。

16. 除非必要，最好不要把与函数返回值类型不同的变量，以编译系统默认的转换方式或强制的转换方式作为返回值返回。

17. 避免函数中不必要语句，防止程序中的垃圾代码。

18. 防止把没有关联的语句放到一个函数中。

19. 功能不明确较小的函数，特别是仅有一个上级函数调用它时，应考虑把它合并到上级函数中，而不必单独存在。

20. 设计高扇入、合理（小于7）的函数。

21. 减少函数本身或函数间的递归调用。

22. 仔细分析模块的功能及性能需求，并进一步细分，同时若有必要画出有关数据流图，据此来进行模块的函数划分与组织。

23. 改进模块中函数的结构，降低函数间的耦合度，并提高函数的独立性以及代码可读性、效率和可维护性。

24. 在多任务操作系统的环境下编程，要注意函数可重入性的构造。

25. 避免使用BOOL参数。

26. 对于提供了返回值的函数，在引用时最好使用其返回值。

27. 当一个过程（函数）中对较长变量（一般是结构的成员）有较多引用时，可以用一个意义相当的宏代替。

 

 

 

7. 可测性

1. 在同一项目组或产品组内，要有一套统一的为集成测试与系统联调准备的调测开关及相应打印函数，并且要有详细的说明。

2．在同一项目组或产品组内，调测打印出的信息串的格式要有统一的形式。信息串中至少要有所在模块名（或源文件名）及行号。

3. 使用断言来发现软件问题，提高代码可测性。

4. 对较复杂的断言加上明确的注释。

5. 用断言确认函数的参数。

6．用断言保证没有定义的特性或功能不被使用。

7. 正式软件产品中应把断言及其它调测代码去掉（即把有关的调测开关关掉）。

8. 用调测开关来切换软件的DEBUG版和正式版，而不要同时存在正式版本和DEBUG版本的不同源文件，以减少维护的难度。

9. 软件的DEBUG版本和发行版本应该统一维护，不允许分家，并且要时刻注意保证两个版本在实现功能上的一致性。

10. 在编写代码之前，应预先设计好程序调试与测试的方法和手段，并设计好各种调测开关及相应测试代码如打印函数等。

11. 调测开关应分为不同级别和类型。

12. 编写防错程序，然后在处理错误之后可用断言宣布发生错误。

8. 程序效率

1. 编程时要经常注意代码的效率。

2. 在保证软件系统的正确性、稳定性、可读性及可测性的前提下，提高代码效率。

3. 局部效率应为全局效率服务，不能因为提高局部效率而对全局效率造成影响。

4. 循环体内工作量最小化。

5. 不应花过多的时间拼命地提高调用不很频繁的函数代码效率。

6. 要仔细地构造或直接用汇编编写调用频繁或性能要求极高的函数。

7. 在多重循环中，应将最忙的循环放在最内层。

8. 尽量减少循环嵌套层次。

9. 避免循环体内含判断语句，应将循环语句置于判断语句的代码块之中。

10. 尽量用乘法或其它方法代替除法，特别是浮点运算中的除法。

 

 

9.       质量保证

 

1.       在软件设计过程中构筑软件质量。

2.       只引用属于自己的存贮空间。

3.       防止引用已经释放的内存空间。

4.       过程/函数中分配的内存，在过程/函数退出之前要释放。

5.       过程/函数中申请的（为打开文件而使用的）文件句柄，在过程/函数退出之前要关闭。

6.       防止内存操作越界。

说明：内存操作主要是指对数组、指针、内存地址等的操作。内存操作越界是软件系统主要错误之一，后果往往非常严重，所以当我们进行这些操作时一定要仔细小心。

7.       认真处理程序所能遇到的各种出错情况。

8.       系统运行之初，要初始化有关变量及运行环境，防止未经初始化的变量被引用。

9.       系统运行之初，要对加载到系统中的数据进行一致性检查。

10.   严禁随意更改其它模块或系统的有关设置和配置。

11.   不能随意改变与其它模块的接口。

12.   充分了解系统的接口之后，再使用系统提供的功能。

13.   编程时，要防止差1错误。

14.   要时刻注意易混淆的操作符。当编完程序后，应从头至尾检查一遍这些操作符，以防止拼写错误。

15.   if语句尽量加上else分支，对没有else分支的语句要小心对待；switch语句必须有default分支。

16.   不要滥用goto语句。

17.   不使用与硬件或操作系统关系很大的语句，而使用建议的标准语句，以提高软件的可移植性和可重用性。

18.   精心地构造、划分子模块，并按“接口”部分及“内核”部分合理地组织子模块，以提高“内核”部分的可移植性和可重用性。

19.   时刻注意表达式是否会上溢、下溢。

20.   使用变量时要注意其边界值的情况。

21. 资源文件（多语言版本支持），如果资源是对语言敏感的，应让该资源与源代码文件脱离，具体方法有下面几种：使用单独的资源文件、DLL文件或其它单独的描述文件（如数据库格式）

 

 

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

 

 

1. 打开编译器的所有告警开关对程序进行编译。

 

2. 在产品软件（项目组）中，要统一编译开关选项。（此处在编码前确定）

 

3. 通过代码走读及审查方式对代码进行检查。

 

4. 项目组内，最好使用相同的编辑器，并使用相同的设置选项。

 

5. 某些语句经编译后产生告警，但如果你认为它是正确的，那么应通过某种手段去掉告警信息。

 

 

6.使用代码检查工具（如C语言用PC-Lint）对源程序检查。

 

7.  使用软件工具（如 LogiSCOPE）进行代码审查。

 

 

11. 代码测试、维护

 

 

1. 清理、整理或优化后的代码要经过审查及测试。

 

2. 尽可能模拟出程序的各种出错情况，对出错处理代码进行充分的测试。

 

3. 仔细测试代码处理数据、变量的边界情况。

 

 

 

12. 宏

 

1. 用宏定义表达式时，要使用完备的括号。

2. 将宏所定义的多条表达式放在大括号中。

3. 使用宏时，不允许参数发生变化。