改善代码质量编程规范 - 学习总结

命名与注释

命名

范围

• 项目名
• 包名
• 接口名
• 类名
• 函数名
• 变量名
• 参数名

原则建议

• 准确达意
  • 对不同作用域，合理选择不同的长度。作用域较小如局部变量，可使用较短的缩写。
  • 参考经典开源系统，使用耳熟能详的名字
• 借助上下文简化命名
  • 借助类的信息简化属性和函数的命名，无需在属性和函数名字中再加入类名
  • 借助函数的信息简化参数的命名
• 增加可读、可搜索醒
  • 避免使用生僻，不好读的英文单词
  • 要符合项目的统一规范，不要使用反直觉的命名
• 与当前项目统一接口命名方式，不要独树一帜

注释

注释应该写什么

• 做什么 - What
• 为什么 - Why
• 怎么做 - How

原则建议

• 注释比代码承载的信息更多
• 注释可以起到总结性文档的作用
• 总结性注释可以帮助让代码结构更加清晰
• 注释并非越多越好
  • 建议类和函数适当添加尽可能详细、全面的注释
  • 函数内部注释减少，通过好的命名、提炼函数、解释性变量、总结性注释来提高代码可读性。

代码风格

类、函数大小

并没有统一的标准规范类与函数的大小。建议函数的大小不要超过显示屏的垂直高度。

代码长数

对于每一行代码依然没有统一标准。建议一行代码不要超过显示器屏的水平宽度。

空行分割单元块

在类的成员变量与函数之间、静态成员变量与普通成员变量之间、各函数之间、甚至各成员变量之间，善用空行分割单元块让这些不同模块的代码之间，界限更加明确。

类成员的排列顺序

不同编程语言有不同的使用习惯。对于Java来说，在类中，成员变量排在函数的前面。成员变量之间或函数之间，都是按照“先静态（静态函数或静态成员变量）、后普通（非静态函数或非静态成员变量）”的方式来排列的。除此之外，成员变量之间或函数之间，还会按照作用域范围从大到小的顺序来排列，先写 public 成员变量或函数，然后是 protected 的，最后是 private 的。

编程技巧

将复杂代码片分割为小单元块

我们要有模块化和抽象思维，善于将大块的复杂逻辑提炼成类或者函数，屏蔽掉细节，让阅读代码的人不至于迷失在细节中，这样能极大地提高代码的可读性。不过，只有代码逻辑比较复杂的时候，我们其实才建议提炼类或者函数。毕竟如果提炼出的函数只包含两三行代码，在阅读代码的时候，还得跳过去看一下，这样反倒增加了阅读成本。

避免函数参数过多

根据实际情况衡量，一般来说小于等于4个参数的函数还是可以接受的。当函数参数大于5个时，我们就觉得参数有点过多了，会影响到代码的可读性。

建议

• 考虑函数是否职责单一，是否能通过拆分成多个函数的方式来减少参数。

• 将函数的参数封装成对象。如果函数是对外暴露的远程接口，将参数封装成对象，还可以提高接口的兼容性。

函数设计要职责单一

类、模块以及函数都要满足单一职责原则。

避免过深的嵌套层次

• 去掉多余的 if 或 else 语句

• 使用编程语言提供的 continue、break、return 关键字，提前退出嵌套

• 调整执行顺序来减少嵌套

• 将部分嵌套逻辑封装成函数调用，以此来减少嵌套

避免魔法数字

使用静态常量替换代码中多次出现的魔法数字。