排版
-
程序块要采用缩进风格编写,缩进的空格数为4个。
-
相对独立的程序块之间、变量说明之后必须加空行。空行可以使程序结构比较清晰。逻辑上关系比较紧密的代码放在一起,逻辑上相对比较独立的部分用空行隔开。
-
较长的语句(>80字符)要分成多行书写,长表达式要在低优先级操作符处划分新行,操作符放在新行之首,划分出的新行要进行适当的缩进,使排版整齐,语句可读
-
若函数或过程中的参数较长,则要进行适当的划分。
-
不允许把多个短语句写在一行中,即一行只写一条语句。
-
if 、for、do、while、case 、switch 、default等语句自占一行,且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。
-
对齐只使用空格键,不使用TAB键。
-
if、for、while、switch等与后面的括号间应加空格,使if等关键字更为突出、明显。
注释
-
说明性文件(如头文件.h文件、.inc 文件、.def 文件、编译说明文件.cfg 等)头部应进行注释,注释必须列出: 版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等,头文件的注释中还应有函数功能简要说明。
-
源文件头部应进行注释,列出: 版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。
-
函数头部应进行注释,列出: 函数的目的/功能、输入参数、输出参数、返回值、调用关系(函数、表)等。
-
注释的内容要清楚、明了,含义准确,防止注释二义性。
-
避免在注释中使用缩写,特别是非常用缩写。
-
注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。
-
全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。
-
将注释与其上面的代码用空行隔开。
标识符命名
-
标识符的命名要清晰、明了,有明确含义,同时使用完整的单词或大家基本可以理解的缩写,避免使人产生误解。
-
对于变量命名,禁止取单个字符(如i、j、k... ),建议除了要有具体含义外,还能表明其变量类型、数据类型等,但i、j、k作局部循环变量是允许的。
-
包名,一般全部小写。
-
类名和接口名称,一般首字母大写,驼峰命名。
-
方法名和变量名:一般第一个单词小写,后续单词首字母大写。
-
常量名:全部大写,单词间用下划线分隔。
可读性
-
注意运算符的优先级,并用括号明确表达式的操作顺序,避免使用默认优先级。
-
避免使用不易理解的数字,用有意义的标识来替代。涉及物理状态或者含有物理意义的常量,不应直接使用数字,必须用有意义的枚举或宏来代替。
变量、结构
-
去掉没必要的公共变量。
-
当向公共变量传递数据时,要十分小心,防止赋与不合理的值或越界等现象发生。
-
防止局部变量与公共变量同名。
-
严禁使用未经初始化的变量作为右值
设计原则
单一职责原则 (Single Responsibility Principle, SRP)
原则说明: 一个类只应该有一个引起它变化的原因。换句话说,每个类应有单一的功能职责。
开闭原则 (Open-Closed Principle, OCP)
原则说明: 软件实体(如类、模块和函数)应当对扩展开放,对修改关闭。即软件需求变更时,应尽量通过新增代码而不是修改现有代码来实现。
里氏替换原则 (Liskov Substitution Principle, LSP)
原则说明: 子类型必须能够替换其基类型,也就是说,任何基类型出现的地方都可以用子类型替代,而程序行为保持不变。
接口隔离原则 (Interface Segregation Principle, ISP)
原则说明: 客户端不应被迫依赖它不需要的接口方法。即多个专门的接口比一个“胖”接口要好。
依赖倒置原则 (Dependency Inversion Principle, DIP)
原则说明: 高层模块不应该依赖低层模块,两者都应该依赖于抽象。抽象不应该依赖细节,细节应该依赖于抽象。
总结
以上是一些编码常用的规范,对于编写出高质量的代码非常重要。一般在实际使用中,还会使用SonarQube等工具进行代码质量监控,只有合格的代码才能合并到开发分支进行测试。