这是我参与「第五届青训营 」伴学笔记创作活动的第 4 天

Go语言的编码规范

编写的代码能够达到正确可靠、简介清晰的目标，比如各种边界条件的考虑、异常情况处理以及可读性和维护性等方面。可以参考Go语言开发者Dave Cheney的The Zen of Go。

如何编写高质量的Go代码，可以从以下几个方面考虑：

• 代码格式
• 注释
• 命名规范
• 控制流程
• 错误和异常处理

1 代码格式

官方提供了自动格式化工具gofmt以及依赖包管理工具goimports等，能够让Go语言代码风格统一。

2 注释

注释应该遵循的规范：

• 注释应该解释代码的作用（注释公共符号）；

• 注释应该揭示代码如何做的（注释实现过程）；

• 注释应该解释代码实现的原因（解释外部因素、提供额外的上下文）；

• 注释应该解释代码什么情况会出错（解释代码的限制条件）。

公共符号始终要注释：包中声明的每个公共符号（变量、常量、函数、结构体等）都需要添加注释；任何及不明显也不简短的公共功能必须注释；对库中的任何函数都必须进行注释；实现接口的方法可以不需要注释。

小结：代码是最好的注释，注释应该提供代码为表达出的上下文信息。

3 命名规范

3.1 变量（variable）命名规范

• 缩略词全部大写，当且仅当其位于变量开头且不需要导出时小写，例如ServeHTTP、xmlHTTPRequest；
• 变量被使用的地方越远，携带的上下文信息则需要更多，例如全局变量等；

3.2 函数（function）命名规范

• 函数名不携带包名的上下文信息；
• 函数名尽量简短；
• 当名为foo的包的某个函数返回Foo类型时可以省略类型信息，返回其他类型T时可以在函数中加入类型信息；

举例：http 包中创建服务的函数

func Serve(l net.Listener, handler Handler) error // Good
func ServeHTTP(l net.Listener, handler Handler) error // Bad

3.3 包（package）命名规范

• 必须只由小写字母组成，不包含下划线等字符；
• 必须包含一定的上下文信息，例如schema、task等；
• 必须不能与标准库同名；
• 尽量不使用常用变量名作为包名，例如使用bufio而不是buf；
• 尽量使用单数而不是复数，例如使用encoding而不是encodings；
• 尽量谨慎地使用缩写，例如使用fmt而不是format。

4 控制流程

• 线性原理，避免复杂嵌套，保证正常流程，如果if语句中两个分支都包含return语句，则可以去掉冗余的else；

• 尽量保证正常代码路径为最小缩进，优先处理错误情况/特殊情况，尽早返回或继续循环来减少嵌套；

5 错误和异常处理

5.1 简单错误

简单错误指的是仅出现一次的错误，在其他地方不需要捕获。

• 优先使用errors.New()创建匿名变量来直接表示简单报错；

• 如果有格式化需求则使用fmt.Errorf来格式化；

5.2 复杂错误

• 错误的Wrap提供了一个error的嵌套能力，从而生成一个error跟踪链；

• 在fmt.Errorf中使用%w来讲一个错误关联至错误链中；

5.3 错误判定

• 判定一个错误是否为特定错误，使用errors.Is而不是==；

• 获取错误链中特定种类的错误，使用errors.As；

5.4 PANIC

• 不建议在业务代码中使用panic；
• 调用函数不包含recover会造成程序崩溃；
• 问题可以被屏蔽或解决时，应该使用error代替panic；
• 在程序启动阶段发生不可逆转的错误时可以在初始化方法或者main函数中使用panic；

5.5 RECOVER

• recover只能在被defer函数中使用，defer语句是后进先出；

• recover不能嵌套生效；

• recover只能在当前goroutine生效；
• 如果需要更多的上下文信息，可以recover后使用debug.Stack()在log中记录当前的调用栈，方便原因查找；