代码质量规范(草稿)
目前本规范状态为草稿, 需要进一步修改谬误, 并进行优化和补充. 欢迎读到这个规范的朋友能够提出宝贵意见, 一同改进!
参考资料如下:
- Build Maintainable software by Joost Visser (O'Reilly Media)
- SIG 软件质量评估标准
1 针对代码单元的质量要求
(这些内容可以利用静态检查工具进行检查)
- 应编写短小的代码单元: 将代码单元(方法或构造函数)的长度限制在15行内. 若不满足, 则将方法展开处理, 或是将方法封装为方法对象.
- 应编写简单的代码单元: 将代码单元的环路复杂度最大限制在 5(分支结点数加 1). 这个是在许多工程中都得到验证的一个合理的值, 最大上限不超过 10. 若不满足, 则采用多态替换或字典对照的解决办法.
- 应编写简单的代码单元接口: 将代码单元的参数个数限制在 4 个内, 如果超过这个限制, 则对方法进行展开处理, 或者是封装参数对象进行处理.
- 严格禁止使用复制粘贴代码: 禁止在同一工程中直接复制粘贴代码, 禁止从其他工程中复制代码到当前工程. 复制粘贴导致的问题比复杂的代码更大, 一处写出的 bug 就是这样被带到多个地方.(同一工程中简单的复制粘贴可以通过 CPD 工具检测).
- 标识符或类型名的最小长度应限制在 2 个以上, 并应避免过长的标识符, 但命名时应先保证命名的易读, 然后再保证长度不过长.
- 一个代码单元的职责应是单一的, 即一个代码单元只做一件事情.
2 针对模块级及其以上的代码质量要求
(如下只有部分内容可以利用静态检测工具检测, 更多是自己在开发过程中时刻去关注).
- 保证模块的单一关注点, 减少单一模块的代码数量(这个可以通过静态检查工具进行检查, 经验值是模块代码量控制在 300 行内).
- 应利用接口隐藏实现, 降低模块间耦合度.
- 应将模块封装为 Framework 或 Library, 再引入使用, 保证主工程的 Code Base 体积小.
- 应保证作为组件接口的模块体积尽可能小, 并且作为接口的模块应避免调用其他组件接口模块, 降低耦合. 实践中常用的做法是使用抽象工厂作为组件接口.
- 应从更高的抽象层级上定义组件接口.
- 保证系统中顶层组件的数量合理, 且各个组件的体积接近, 经验值是控制在 6 到 12 个之间. 实践中应更多关注系统功能的划分是否合理, 若是一个合理的系统, 其顶层组件数量和组件体积都能够很好符合这条规则的要求.
- 应保证单一代码库的体积尽可能小. 可行的做法有: 1)防止代码库中出现复制粘贴代码. 2)相同功能前提下的代码实现应简单小巧. 3)利用 Framework 或 library 引入三方功能. 4)将大系统分解为若干独立的小系统.
3 对于代码测试的要求
- 应编写完整的代码单元测试, 单元测试应保证至少 80% 的覆盖率.
- 应针对模块功能, 编写相应的集成测试.
- 应针对系统功能, 实现相应的端对端测试.
- 应进行自动化测试, 可利用相应平台的测试 Framework 编写测试.
- 应保证测试实现代码的质量符合本规范第一第二及第四节质量要求.
4 其他要求
- 在代码中不应保留 Dead Code: 1)应清理不再被调用的代码. 2)应清理其结果不再被使用的代码. 3)应清理被注释掉的代码. 4)应清理永远不会被执行到的代码单元组成部分.
- 在代码中不应出现魔法数字. 遇到魔法数字的情况下应替换为常量进行表示.
- 应对代码中的异常进行正确处理: 1)应保证代码中的异常都能被捕捉. 2)应尽可能按特定异常类型进行捕捉. 3)应根据要求对异常进行合理处理, 若显示给最终用户, 需要以用户友好的形式呈现.
- 应根据优先级和着眼点将本规范合理应用到实际软件工程施工中. 其中代码单元质量要求应优先于模块或组件进行落实.
