编写可维护Go语言代码建议

指导原则

• 简单性

• 可读性

• 生产力

实现松散耦合

• 使用接口描述函数或方法所需要的行为

• 避免合用全局状态

  • 将相关变量作为字段移动到需要它们的结构上

  • 使用接口减少行为与实现之间的耦合

标识符

好的名字

• 很简洁

• 是描述性的

• 应该是可以预测的

指导

• 短变量名称在声明和上次使用之间的距离很短时效果很好。

• 长变量名称需要证明自己的合理性; 名称越长，需要提供的价值越高。冗长的名称与页面上的重量相比，信号量较小。

• 请勿在变量名称中包含类型名称。

• 常量应该描述它们持有的值，而不是该如何使用。

• 对于循环和分支使用单字母变量，参数和返回值使用单个字，函数和包级别声明使用多个单词

• 方法、接口和包使用单个词。

• 请记住，包的名称是调用者用来引用名称的一部分，因此要好好利用这一点。

理解 上下文是关键

规范要求

• 不要用变更类型命名你的变量

• 使用一致的命名方式

• 使用一致的声明样式

  • 声明变量，但没有初始化，使用var

  • 声明同时初始化时，使用:=

注释

注释应该做的三件事：

• 注释应该解释其作用

• 注释应该解释其如何做

• 注释应该解释其原因

怎么注释

• 关于变量和常量的注释就描述其内容而非其目的

• 公共符号始终要注释

• 不要注释不好的代码，将它重写

• 与其注释一段代码，不如重构它

Google Style的两条规则：

• 任何既不明显也不简短的公共功能必须予以注释。

• 无论长度或复杂程序如何，对库中的任何函数都必须进行注释。

包的设计

• 好的包名应该是唯一的

• 避免使用类似base、common或unil的包的名称

  • 重复比错误的抽象的性价比高很多

• 尽量return而不是深度嵌套（通过使用 guard clauses实现）

• 让零值更有用

  • 给你的结构一个有用的零值

• 避免包级别状态

项目结构

• 考虑更少、更大的包

• 通过import语句将代码排列到文件中

• 优先内部测试再到外部测试

• 使用internal包来减少公共API

• 确保main包内容尽可能的少

API设计

• 设计难以被误用的API

• 警惕采用几个相同类型参数的函数

• 不鼓励使用nil作为参数

• 首选可变参数函数而非[]T参数

错误处理

• 通过消除错误来消除错误处理

• 当遇到难以忍受的错误处理时，请尝试将某些操作提取到辅助程序类型中

• 错误只处理一次

• 为错误添加相关内容

• 使用 github.com/pkg/errors 包装 errors

并发

Go 语言以 channels 以及 select 和 go 语句来支持并发

• 保持自己忙碌或做自己的工作： 如果你的 goroutine 在得到另一个结果之前无法取得进展，那么让自己完成此工作而不是委托给其他 goroutine 会更简单

• 将并发性留给调用者： 如果你的函数启动了 goroutine，你必须为调用者提供一种明确停止 goroutine 的方法。 把异步执行函数的决定留给该函数的调用者通常会更容易些。

• 永远不要启动一个停止不了的goroutine