Go 高质量编程、编码规范|青训营

前言

本文将介绍Go语言的高质量编程、Go语言编码规范。

简介

什么是高质量？

在编写代码时，能够达到正确可靠、简洁清晰的目标可称之为高质量代码。

高质量代码需要满足的条件：

各种边界条件是否考虑完备
异常情况处理周全、稳定性的保证
代码易读易维护

编写高质量代码，团队之间相互阅读代码才会比较顺畅，同时也能提高团队开发效率。做到高质量代码，别人在看代码时才能清楚明白代码的作用，才能够放心的去重构或进行代码优化，才能放心的在原有代码基础之上增加新的功能，不用担心出现无法预料到的东西。

编程原则

实际应用场景千变万化，各种语言的特性和语法各不相同，但是高质量编程遵循的原则是相同的。

简单性

消除"多余的复杂性"，以简单清晰的逻辑编写代码
不理解的代码无法修复改进

可读性

代码是写给人看的，而不是机器
编写可维护代码的第一步是确保代码可读

生产力

团队整体工作效率非常重要

编码规范

如何编写高质量的Go代码？有一些公认的开源的编码规范可以提供我们参考，像一些公司内部也有自己的编码规范。

下面选几个重要的规范来介绍下：

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

代码格式

代码各种能统一的话，团队之间合作就能把关注点放在具体的逻辑上，提高效率。

推荐使用gofmt自动格式化代码

gofmt

Go语言官方提供的工具，能自动格式化Go语言代码为官方统一风格，常见IDE都支持方便的配置

goimports

也是Go语言官方提供的工具，实际等于gofmt加上依赖包管理，自动增删依赖的包引用、将依赖包按字母序排序并分类。可以在下方链接找到答案：

GoLand (windows)配置 go fmt 与 goimports_goland 增加gofmt goimport_情、狠现实的博客-CSDN博客

注释

写代码时不加注释，当时也许只有你和上帝知道，但过了几年，也许只有上帝才能知道了。

Good code has lots of comments, bad code requires lots of comments. 好的代码有很多注释，坏的代码需要很多注释。

公共符号始终要注释

包中声明的每个公共的符号：变量、常量、函数以及结构都需要添加注释
任何既不明显也不简单的公共功能必须予以注释
无论长度或复杂成都如何，对库中的任何函数都必须进行注释
例外：不需要注释接线接口的方法。

注释很重要，能够快速理解代码的含义，那注释应该怎么做呢？

应该解释代码作用
应该解释代码如何做的
应该解释代码实现的原因
应该解释代码什么情况会出现错误

解释代码作用

适合注释公共符号，比如公共的常量、函数。如果一个函数通过名字就能知道他的作用，那么这样的函数可以不用加注释。

解释代码如何做的

适合注释实现过程

对一些实现逻辑复杂的代码、调用函数功能不是很明显的代码逻辑加上注释。

解释代码实现的原因

适合解析代码的外部因素，提供额外上下文，让人知道为什么这样做，要不然后续再维护代码时，会让人很难理解。

解释出错情况

适合解释代码的限制条件，通过注释可以知道在使用的过程中应该有哪些注意的点，以防在使用的过程中，产生错误。

命名规范

命名规范的核心目标是降低阅读理解代码的成本，重点考虑上下文信息，设计简洁清晰的名称。

Good naming is like a good joke,if you have to explian it, it is not funny. 好的命名就像一个好笑话，如果你必须解释她，那就不好笑了。

变量

简洁胜于冗长
缩略词全大写，但当其位于变量开头且不需要导出时，使用全小写
- 例如使用ServeHTTP而不是ServeHttp
- 使用XMLHTTPRequest或者xmlHTTPRequest
变量距离其被使用的地方越远，则需要携带越多的上下文信息
- 全局变量在其名字中需要更多的上下文信息，使得在不同地方可以轻易辨认出其含义

go 复制代码

go
复制代码
复制代码
// 不好的代码
for index := 0; index < len(s); index++ {
    // so something
}
// 好的代码
for i := 0; i < len(s); i++ {
    // so something
}

i 和 index 的作用域范围仅限于for循环内部时，index的额外冗长几乎没有增加对于程序的理解。

函数

函数名不携带包名的上下文信息，因为包名和函数名总数成对出现的
函数名尽量简短
当名为foo的包某个函数返回类型Foo时，可以省略类型信息而不导致歧义
当名为foo的包某个函数返回类型T时(T并不是Foo)，可以在函数名中加入类型信息

包名

只由小写字母组成，不包含大写字母和下划线等字符
简短并包含一定的上下文信息，例如schema、task等
不要与标准库同名，例如不要使用sync、strings等

以下规则尽量满足，以标准库包名为例

不使用常用变量名作为包名，例如使用bufio而不是buf
使用单数而不是复数，例如使用encoding而不是encodings
谨慎地使用缩写，例如使用fmt在不破坏上下文的情况下比format更加简短

控制流程

流程控制要遵循线性原理，处理逻辑尽量走直线，避免复杂的嵌套分支；正常流程代码要沿着屏幕向下移动；

好的流程可以提升代码的可维护性和可读性。

在实际项目中，故障问题大多出现在复杂的条件语句和循环语句中。

好的流程控制要遵循以下几点：

避免嵌套，保持正常流程清晰
kotlin 复制代码
```
go
复制代码
复制代码
// 不好的代码
if foo {
    return x
} else {
    return nil
}
// 好的代码
if foo {
    return x
}
return nill
```
如果两个分支都包含return语句，则可以去除冗余的else(也被称为卫语句)。

尽量保持正常代码路径为最小缩进

优先处理错误情况/特殊情况，尽早返回或继续循环来减少嵌套

go 复制代码

go
复制代码
复制代码
// 不好的代码
func OneFunc() error {
    err := dosomething()
    if err == nil {
        err := dosomething()
        if err == nil {
            return nil
        }
        return err
    }
    return err
}
// 好的代码
func OneFunc() error {
    if err := dosomething(); err != nil {
        return err
    }
    if err := doAnotherthing(); err != nil {
        return err
    }
    return nil
}

错误和异常处理

error尽可能提供简明的上下文信息链，方便定位问题，panic用于真正异常的情况，recover生效范围，在当前goroutine的被defer的函数中生效。

简单错误

简单的错误指的是仅出现一次的错误，且在其他地方不需要捕获该错误
优先使用errors.New来创建匿名变量来直接表示简单错误
如果有格式化的需求，使用fmt.Errorf

错误的Wrap和Unwrap

错误的Wrap实际上是提供了一个error嵌套另一个error的能力，从而生成一个error的跟踪链
在fmt.Errorf中使用%w关键字来将一个错误关联至错误链中

错误判定

判定一个错误是否为特定错误，使用errors.Is
不同于使用==，使用该方法可以判定错误链上的所有错误是否含有特定的错误
在错误链上获取特定种类的错误，使用errors.As

panic

不建议在业务代码中使用panic
调用函数不包含recover会造成程序崩溃
若问题可以被屏蔽或解决，建议使用error代替panic
当程序启动阶段发生不可逆转的错误时，可以在init或main函数中使用panic

recover

recover只能在被defer的函数中使用
嵌套无法生效
只在当前goroutine生效
defer的语句是后进先出
如果需要更多的上下文信息，可以recover后再log中记录当前的调用栈