更清晰
- 使用更具描述性的变量名称
- 添加额外的评论
- 使用空白与注释来划分代码
- 将代码重构为独立的函数 / 方法,使其更加模块化
简约
- 从头至尾都易于阅读
- 不预设你已经知道它在做什么
- 不预设你能记住前面所有的代码
- 不含非必要的抽象层次
- 不含过于通用的命名
- 让读者清楚地了解到传值与决定的传播情况
- 有注释,解释为什么,而不是代码正在做什么,以避免未来的歧义
- 有独立的文档
- 包含有效的错误与失败用例测试
- 往往不是看起来“聪明“的代码
在代码的简单性和AP使用的简单性之间可能会需要权衡。例如,让代码更复杂可能是值得的,这样API的终端用户可以更容易地正确调用API。相反,把一些额外的工作留给AP的终端用户也是值得的,这样代码就会保持简单和容易理解。
可维护性
- 容易让未来的程序员正确进行修改
- 拥有结构化的API,使其能够优雅地增加
- 清楚代码预设条件,并选择映射到问题结构而不是代码结构的抽象
- 避免不必要的耦合,不包括不使用的功能
- 有一个全面的测试套件,以确保预期行为可控、重要逻辑正确,并且测试在失败的情况下提供清晰、可操作的诊断
具体规则:
- 函数和方法名称不应使用Get或get前缀,除非底层概念使用单词”get”(例如HTTP GET)。此时,更应该直接以名词开头的名称,例如使用Counts 而不是GetCounts。
- Variable names 一般的经验法则是,名称的长度应与其范围的大小成正比,并与其在该范围内使用的次数成反比。在文件范围内创建的变量可能需要多个单词,而单个内部块作用域内的变量可能是单个单词甚至只是一两个字符,以保持代码清晰并避免无关信息。
一些必须要遵守的style:
error是func最后一个参数
采用context。Context参数的函数通常应返回error,以便调用者可以确定上下文是否在函数运行时被取消