快速改善代码质量的方法

[banli17]

命名和注释

命名

• 大到项目名、模块名、包名、对外暴露的接口，小到类名、函数名、变量名、参数名，只要是做开发
• 实在想不到好名字的时候，可以去 GitHub 上用相关的关键词联想搜索一下，看看类似的代码是怎么命名的。
• 命名长度
  • 长命名容易理解，但是会经常导致代码分割成两行(行长度限制情况下)，这会影响代码可读性
  • 短命名不如长命名容易理解，如果是默认、熟知的词推荐缩写
  • 作用域小的变量，可以使用短命名，如临时变量。作用域大的，推荐用长命名。
  • 命名的原则，让别人能快速准确理解其意义，要换位思考。
• 利用长下文简化命名
  • 类和函数的变量，如User 类里，用户名就无需使用 username，而可以直接用 name。
  • 函数参数
• 命名可读可搜索
  • 要符合整体项目命名习惯，如都用 spaceName，你就不要用 namespace
  • 不要用生僻、不好读的词
• 命名接口和抽象类: 做到项目种命名统一
  • 接口: 常见2种命名方式
    • 前缀加 I，如 IUserService
    • 不加前缀，对应实现类加后缀 Impl，如 UserServiceImpl
  • 抽象类：常见2种命名方式
    • 前缀加 Abstract，如 AbstractConfiguration
    • 不带前缀，直接用 Configuration

注释

注释是对代码的补充, 目的是让代码更容易被看懂。注释内容包含下面几个部分：

• 做什么: 对于函数或变量，如果命名好，可以不写，而对于类承载的信息较多，命名不能完全体现。
• 为什么
• 怎么做：代码复杂不好拆分的函数可以写一些总结性注释，让代码结构更清晰
• 如何用(如果复杂性大)

/**
* (what)

* (why)

* (how)
*/
function isValidPasword(password) {
  // check if password is null or empty

  // check if the length of password is between 4 and 64

  // check if password contains only a~z,0~9,dot
}

注释不要太多也不要太少，类和函数一定要写注释，而且尽可能全面，详细，函数内部的注释要相对少点，通过好的命名、提炼函数、总结性注释来提高代码可读性。

注释有一定维护成本，改了代码也要更新相应注释。

[banli17]

代码风格

类、函数长度

• 太长不容易阅读和维护，太短读起来跳来跳去，体验也不好
• 函数不超过 50 行，即不超过一屏，不用滚动。
• 类读起来头大时或类职责过多时，就可以合理拆分

一行代码限制在 100 字符。不要超过 IDE 显示宽度。 善用空行分割单元块 代码缩进统一，推荐两格 大括号风格统一，一般不要另起一行，如 if( ) { 类种成员排列顺序：先静态，后普通。先 public 后 protected，最后 private。对于 import 引用包，按照字母排序。

[banli17]

编程技巧

• 在代码逻辑复杂时，拆分为更小单元块。如果太小，阅读起来总是跳转，反而影响阅读。
• 避免函数参数过多，建议小于 5 个。
  • 考虑函数职责是否单一，是否能通过拆分来减少参数
  • 将函数参数封装为对象, 同时提高兼容性(比如增加参数时，不需要改参数)
• 勿用参数来控制函数内部逻辑
  • 可以将逻辑拆分为两个函数
• 函数设计要职责单一
• 移除过深的嵌套层次，最好不超过两层。理解费劲、多次缩进影响阅读
  • 去掉多余的 if 或 else
  • 使用 continue、break、return 提前跳出嵌套
  • 调整执行顺序, 如将 else 里的拿到前面取反判断，后面代码就不需要 if 了。
  • 将部分逻辑封装为函数
• 使用解释性变量，如 PI、isSummer

// 拆分成两个函数的调用方式
boolean isVip = false;
//...省略其他逻辑...
if (isVip) {
  buyCourseForVip(userId, courseId);
} else {
  buyCourse(userId, courseId);
}

// 保留标识参数的调用方式更加简洁
boolean isVip = false;
//...省略其他逻辑...
buyCourse(userId, courseId, isVip);