《码出高效：Java开发手册》 第3章 代码风格

流水淡，碧天长，鸿雁成行。编码风格，简洁清爽，反引无限风光。

3.1 命名规约

  • 命名符合语言特征
  • 命名体现代码元素特征
    • 有助于快速识别命名对象的作用。
    • 推荐在 Java 命名时遵循以下规约：
      • 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义 则可以使用复数形式。
      • 抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类命名以它要测试的类名开始，以 Test 结尾。
      • 类型与中括号紧挨相连来定义数组。
      • 枚举类名带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。
  • 命名最好望文知义
    • 减少注释内容，达到自解释的目的。

常量：

  • 全局常量：字母全大写，单词间加下划线
    • public static final
  • 类内常量：字母全大写，单词间加下划线
    • private static final
  • 局部常量：小驼峰形式
    • 方法常量：方法或代码块内常量，定义增加 final 标识
    • 参数常量：形参增加 final 标识

变量：

  • 一般采用小驼峰格式
  • 在 POJO 类中，布尔型字段名不要加 is 前缀
    • 但在数据库中，推荐采用 is_xxx 的命名格式

3.2 代码展示风格

3.2.1 缩进、空格与空行

  • 缩进
    • 推荐使用 4 个空格缩进
  • 空格
    • 任何二目、三目运算符的左右两边都必须加一个空格。
    • 注释的双斜线与注释内容之间有且仅有一个空格。
    • 方法参数在定义和传入时，多个参数逗号后边必须加空格。
    • 没有必要增加若干空格使变量的赋值等号与上一行对应位置的等号对齐。
    • 如果是大括号内为空，则简洁地写成 {} 即可，大括号中间无须换行和空格。
    • 左右小括号与括号内部的相邻字符之间不要出现空格。
    • 左大括号前需要加空格。
  • 空行
    • 提升代码阅读的体验。
    • 在方法定义之后、属性定义与方法之间、不同逻辑、不同语义、不同业务的代码之间通过空行来分隔。

3.2.2 换行与高度

  • 换行
    • 单行字符数不超过 120 个
    • 超出时按照以下原则换行
      • 第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进；
      • 运算符与下文一起换行；
      • 方法调用的点符号与下文一起换行；
      • 方法调用中的多个参数需要换行时，在逗号后换行；
      • 在括号前不要换行；
  • 方法行数限制
    • 约定单个方法的总行数不超过 80 行。

3.2.3 控制语句

  • 在 if、else、for、while、do-while 等语句中必须使用大括号。
  • 在条件表达式中不允许有赋值操作，也不允许在判断表达式中出现复杂的逻辑组合。
  • 多层嵌套不要超过 3 层。
  • 避免采用取反逻辑运算符。

3.3 代码注释

  • 注释三要素：
    • Nothing is strange
      • 要写注释
    • Less is more
      • 但不要写无用的注释
    • Advance with the times
      • 修改代码时应同时修改注释
  • 注释格式
    • Javadoc 规范 /** */
    • 简单注释
      • 必须写在代码上方，不要使用行尾注释。
      • 注释通常添加在非常必要的地方。