清晰

  • 使用更具描述性的变量名称
  • 添加额外的评论
  • 使用空白与注释来划分代码
  • 将代码重构为独立的函数 / 方法,使其更加模块化
 
简约

  • 从头至尾都易于阅读
  • 不预设你已经知道它在做什么
  • 不预设你能记住前面所有的代码
  • 不含非必要的抽象层次
  • 不含过于通用的命名
  • 让读者清楚地了解到传值与决定的传播情况
  • 有注释,解释为什么,而不是代码正在做什么,以避免未来的歧义
  • 有独立的文档
  • 包含有效的错误与失败用例测试
  • 往往不是看起来“聪明“的代码
 

在代码的简单性和AP使用的简单性之间可能会需要权衡。例如,让代码更复杂可能是值得的,这样API的终端用户可以更容易地正确调用API。相反,把一些额外的工作留给AP的终端用户也是值得的,这样代码就会保持简单和容易理解。
 
可维护性

  • 容易让未来的程序员正确进行修改
  • 拥有结构化的API,使其能够优雅地增加
  • 清楚代码预设条件,并选择映射到问题结构而不是代码结构的抽象
  • 避免不必要的耦合,不包括不使用的功能
  • 有一个全面的测试套件,以确保预期行为可控、重要逻辑正确,并且测试在失败的情况下提供清晰、可操作的诊断
 

具体规则:
  • 函数和方法名称不应使用Get或get前缀,除非底层概念使用单词”get”(例如HTTP GET)。此时,更应该直接以名词开头的名称,例如使用Counts 而不是GetCounts。
  • Variable names 一般的经验法则是,名称的长度应与其范围的大小成正比,并与其在该范围内使用的次数成反比。在文件范围内创建的变量可能需要多个单词,而单个内部块作用域内的变量可能是单个单词甚至只是一两个字符,以保持代码清晰并避免无关信息。
 

一些必须要遵守的style:
 
error是func最后一个参数
采用context。Context参数的函数通常应返回error,以便调用者可以确定上下文是否在函数运行时被取消