1.1 简介

什么是高质量？

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

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

编程原则

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

简单性

消除“多余的复杂性”，以简单清晰的逻辑编写代码

不理解的代码无法修复改进

可读性

代码是写给人看的，而不是机器

编写可维护代码的第一步是确保代码可读

生产力

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

——Dave Cheney

1.2 编码规范（如何编写高质量的Go代码）

1.2.1 代码格式

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

gofmt

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

goimports

也是Go语言官方提供的工具，实际等于gofmt加上依赖包管理，自动增删依赖的包引用、将依赖包按字母序排序并分类。

（Goland内置有自动格式化代码）

1.2.2 注释

Good code has lots of comments, bad code requires lots of comments.

好的代码有很多注释，坏的代码需要很多注释。

——Dave Thomas and Andrew Hunt

注释应该做的

应该解释代码作用

适合注释公共符号，如果通过函数名就能知道功能就不用注释了

应该解释代码如何做的

适合注释实现过程

应该解释代码实现的原因

适合解析代码的外部因素，提供额外上下文

应该解释代码什么情况会出现错误

适合解释代码的限制条件

公共符号始终要注释

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

1.2.3 命名规范

变量

简洁胜于冗长
缩略词全大写，但当其位于变量开头且不需要导出时，使用全小写
- 例如使用ServeHTTP而不是ServeHttp
- 使用XMLHTTPRequest或者xmlHTTPRequest
变量距离其被使用的地方越远，则需要携带越多的上下文信息
- 全局变量在其名字中需要更多的上下文信息，使得在不同地方可以轻易辨认出其含义
作用域范围仅限于for循环内部时，用i这样的命名简洁
函数签名参数命名时如果用t而非deadline这样的命名会降低变量名的信息量

函数

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

包名

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

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

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

Good naming is like a good joke,if you have to explian it, it is not funny.

好的命名就像一个好笑话，如果你必须解释她，那就不好笑了。

——Dave Cheney

另外还可以说，Go语言的命名规范如下：

包名：采用小写字母，不使用下划线或混合大小写。
例：package main

变量和函数名：采用驼峰命名法。
例：var myVariable int
func myFunction() {}

公共（可外部调用）的标识符（常量、变量、类型、函数）：首字母大写。
例：const Pi = 3.14159
var MyVariable int
type MyStruct struct{}
func MyFunction() {}

私有（仅在包内部可见）的标识符：首字母小写。
例：var internalVariable int
func internalFunction() {}

结构体的成员变量：首字母大写表示公共，首字母小写表示私有。
例：type MyStruct struct {
PublicField int
privateField int
}

接口的命名：采用以er结尾的方式，表示该接口提供的一组行为。
例：type Writer interface {
Write([]byte) (int, error)
}

测试函数：以Test开头，并遵循驼峰命名法，测试函数的参数必须是 *testing.T 类型。
例：func TestMyFunction(t *testing.T) {}

缩写的命名规范：只使用全大写字母。
例：URL, HTTP

需要注意的是，在Go语言中，一般采用短小的命名，避免使用无意义的单个字母命名，而应该使用具有描述性的名称。此外，命名应该尽量简洁明了，不要过度使用缩写。

1.2.4 控制流程

避免嵌套，保持正常流程清晰

// 不好的代码 
if foo { 
    return x 
} else { 
return nil 
} 
// 好的代码 
if foo { 
    return x 
} 
return nil

如果两个分支都包含return语句，则可以去除冗余的else

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

// 不好的代码
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
}

小结

流程控制要遵循线性原理，处理逻辑尽量走直线，避免复杂的嵌套分支
正常流程代码要沿着屏幕向下移动
提升代码的可维护性和可读性
故障问题大多出现在复杂的条件语句和循环语句中

1.2.5 错误和异常处理

简单错误

简单的错误指的是仅出现一次的错误，且在其他地方不需要捕获该错误
优先使用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中记录当前的调用栈

小结

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

高质量编程简介及代码规范笔记 ｜ 青训营