通用

保持一致

要收敛，不要发散，混乱的系统是没办法维护的。

• 任何地方，新增和修改内容时应该和原风格一致。
• 修改前要先熟悉已有风格，遵守规范。
• 如果有疑问可与原作沟通，不能自作主张。

空格

• 多个参数逗号后空格。

  System.out.print("%d", 123);
  

• 注释标记后空格。

  sendMail();// 发送邮件
  

• 操作符前后空格。

  int a = 5 + 6;
  

• 方法调用的括号前后不空格。

  int a = Integer.parse("123");
  

• 缩进使用空格而不是Tab。

• 语言允许的情况下，用两个空格缩进而不是四个。

• 强制类型转换时，右括号与强制转换值之间不需要任何空格。

空行

• 20 行以内的小方法尽量不要加。
• 用空行划分逻辑意味着需要拆分方法，有时候不值得这么做，慎用空行。
• 一般一次只空两行。

列数

所有语言每行不得超过 120 列，一下情况可例外：

• Markdown 中不限制，编辑器应设置自动 wrap。
• 注释中引用很长的链接时。

引号

有的语言声明字符串同时允许单引号、双引号，此时一般优先使用无引号、单引号，必要时再使用双引号。

字符串

进行字符串拼接时首选插值语法而不是用运算符连接，提高可读性。

命名

原则

• 遵守英语语法，注意单复数、词性、时态，读起来要通顺、自然。
• 遵守编程语言惯例。
• How to Name Things：
  • 保持一致，不要自己发明。
  • 名字尽力明确。
  • 描述要详细，尽管名字可能会很长。
  • 避免缩写，如果必须要，name应该记下来。
  • 避免歧义、模糊不清。
  • 避免魔术值。
  • 对于布尔值，确定的比不确定的好。
  • 正确使用单复数。
  • 正确使用时态。
  • 正确地拼写。
  • 使用动词 + 名词来为函数、方法命名。
  • 使用形容词（可选） + 名词来为类命名。
  • 不要害怕重命名。
  • 多花些时间思考。

惯例

• 计数用 count、times，总和用 sum。
• 时间用 xxxAt 的形式，表已经发生的用过去式，比如 publishedAt，表将要发生的用现在时，比如 publishAt。
• 是否用 isXXX、doesXXX、shouldXXX、canXXX 的形式，尤其注意：不是什么单词前面都可以放 is、are 等系词，名词、形容词才可以。

排序

在新增代码时，应该遵循下面的原则：

• 找出当前文件或相关代码的排序规律，按这个规律把新代码插到合适的位置。
• 如果原有代码不够多、没有明显规律，按下面的规律排序：
  • 方法排序一般把全部 public 方法排前面，然后是 private 方法。
  • 把相关的放在一起。
  • 按界面顺序排序，例如接收表单的字段排序与界面上展示的顺序保持一致。
  • 按使用顺序排序，先被使用的、使用频率高的排前面，后被使用、使用频率第的排后面。
  • 按自然顺序排序。

注释

• 代码的意图尽量通过编码表达，而不是使用注释。
• 代码明确的情况下不要加重复注释。
• 一些合理的注释：
  • 纲要性注释，简要描述一个文件、一个类。
  • 复杂业务逻辑、算法。
  • 代码作用并不直观。
  • 存在多种可选方案，解释选择这种的原因。
  • 因为某些现实导致代码不一致、不优雅或存在副作用时，注明原因及后果。
  • 参考了外部资料，注明链接。
  • 临时标记注释，例如 TODO。
• 注释随代码更新，注释里不要包含不必要的细节。
• 注释掉的代码属于无用代码，除非有额外注释说明，否则应该在提交前删除。

日志

• 不要滥用 error 级别日志。
• message 应为固定字符串，不要在里面拼接变量。
• 对于细节、流程日志，要说明影响、逻辑后续的走向。
• 对于错误、异常，尽量说出问题的本质。
• 不要过度打印日志。

异常

• 不要吞掉异常，除非错误可忽略，否则不能只 catch 但是不处理。
• 不要过度处理异常，一般使用面向切面的方式。
• 保留原始异常（caused by）。
• 不使用返回值表示成功和失败，避免要求客户端对返回值进行判断。
• 如果要重试，必须加次数限制。