代码质量规范(草稿)

目前本规范状态为草稿, 需要进一步修改谬误, 并进行优化和补充. 欢迎读到这个规范的朋友能够提出宝贵意见, 一同改进!

参考资料如下:

1 针对代码单元的质量要求

(这些内容可以利用静态检查工具进行检查)

应编写短小的代码单元: 将代码单元(方法或构造函数)的长度限制在15行内. 若不满足, 则将方法展开处理, 或是将方法封装为方法对象.
应编写简单的代码单元: 将代码单元的环路复杂度最大限制在 5(分支结点数加 1). 这个是在许多工程中都得到验证的一个合理的值, 最大上限不超过 10. 若不满足, 则采用多态替换或字典对照的解决办法.
应编写简单的代码单元接口: 将代码单元的参数个数限制在 4 个内, 如果超过这个限制, 则对方法进行展开处理, 或者是封装参数对象进行处理.
严格禁止使用复制粘贴代码: 禁止在同一工程中直接复制粘贴代码, 禁止从其他工程中复制代码到当前工程. 复制粘贴导致的问题比复杂的代码更大, 一处写出的 bug 就是这样被带到多个地方.(同一工程中简单的复制粘贴可以通过 CPD 工具检测).
标识符或类型名的最小长度应限制在 2 个以上, 并应避免过长的标识符, 但命名时应先保证命名的易读, 然后再保证长度不过长.
一个代码单元的职责应是单一的, 即一个代码单元只做一件事情.

(如下只有部分内容可以利用静态检测工具检测, 更多是自己在开发过程中时刻去关注).

保证模块的单一关注点, 减少单一模块的代码数量(这个可以通过静态检查工具进行检查, 经验值是模块代码量控制在 300 行内).
应利用接口隐藏实现, 降低模块间耦合度.
应将模块封装为 Framework 或 Library, 再引入使用, 保证主工程的 Code Base 体积小.
应保证作为组件接口的模块体积尽可能小, 并且作为接口的模块应避免调用其他组件接口模块, 降低耦合. 实践中常用的做法是使用抽象工厂作为组件接口.
应从更高的抽象层级上定义组件接口.
保证系统中顶层组件的数量合理, 且各个组件的体积接近, 经验值是控制在 6 到 12 个之间. 实践中应更多关注系统功能的划分是否合理, 若是一个合理的系统, 其顶层组件数量和组件体积都能够很好符合这条规则的要求.
应保证单一代码库的体积尽可能小. 可行的做法有: 1)防止代码库中出现复制粘贴代码. 2)相同功能前提下的代码实现应简单小巧. 3)利用 Framework 或 library 引入三方功能. 4)将大系统分解为若干独立的小系统.

在代码中不应保留 Dead Code: 1)应清理不再被调用的代码. 2)应清理其结果不再被使用的代码. 3)应清理被注释掉的代码. 4)应清理永远不会被执行到的代码单元组成部分.
在代码中不应出现魔法数字. 遇到魔法数字的情况下应替换为常量进行表示.
应对代码中的异常进行正确处理: 1)应保证代码中的异常都能被捕捉. 2)应尽可能按特定异常类型进行捕捉. 3)应根据要求对异常进行合理处理, 若显示给最终用户, 需要以用户友好的形式呈现.
应根据优先级和着眼点将本规范合理应用到实际软件工程施工中. 其中代码单元质量要求应优先于模块或组件进行落实.