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

高质量编程简介及编码规范

1. 简介

什么是高质量 —— 编写的代码能够达到正确可靠、简介清晰的目标可称之为高质量代码

各种边界条件是否考虑完备
异常情况处理，稳定性保证
易读易维护

编程原则

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

简单性

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

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

可读性

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

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

生产力

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

2. 编码规范

如何编写高质量的Go代码？

代码格式

注释

命名规范

控制流程

错误和异常处理

2.1 代码格式

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

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

2.2 注释

注释应该做的

解释代码作用

解释代码如何做的

解释代码实现的原因

解释代码什么情况会出错

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

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

公共符号始终要注释

包中声明的每个公共的符号：变量、常量、函数以及结构都需要添加注释
任何既不明显也不简短的公共功能必须予以注释
无论长度或复杂程度如何，对库中的任何函数都必须进行注释
删除没有提供有用信息的注释，比如它没有告诉你这个方法做了什么，仅仅告诉你去看其他地方的文档。
```
// Read implements the io.Reader interface
func (r *FileReader) Read(buf []byte) (int, error)
//
```

2.3 命名规范

命名规范应该做的

简洁胜于冗长

缩略词全大写，但当其位于变量开头且不需要导出时，使用全小写

例如使用ServeHTTP而不是ServeHttp

使用XMLHTTPRequest或者xmlHTTPRequest

变量距离其被使用的地方越远，则需要携带越多的上下文信息

全局变量在其名字中需要更多的上下文信息，使得在不同地方可以轻易辨认出其含义

变量命名

示例1：i和index的作用域范围仅限于for循环内部时，index的额外冗长几乎没有增加对于程序的理解，所以用更简单的i是最好的
```
// Bad
for index := 0; index < len(s); index++ {
    // do something
}

// Good
for i := 0; i < len(s); i++ {
    // do something
}
```
示例2：
- 将deadline替换成t降低了变量名的信息量
- t常代指任意时间
- deadline指截止时间，有特定的含义
- 函数提供给外部调用时，签名的信息很重要，要将自己的功能准确表现出来，自动提示一般也会提示函数的方法签名，通过参数名更好的理解功能很有必要，节省时间
```
// Good
func (c *Client) send(req *Request, deadline    time.Time)

// Bad
func (c *Client) send(req *Request,t time.Time)
```

函数命名

函数名不携带包名的上下文信息，因为包名和函数名总是成对出现的
函数名尽量简短
当名为foo的包某个函数返回类型Foo时，可以省略类型信息而不导致歧义
当名为foo的包某个函数返回类型T时（T并不是Foo），可以在函数名中加入类型信息
提问：http包中创建服务的函数如何命名更好？

func Serve(l net.Listener, handler Handler) error

func ServeHTTP(l net.Listener, handler Handler) error

我们在实际使用的时候，是会带上包名的，即http.Serve和http.ServeHTTP，所以不需要在函数名中再添加包信息，选择前者更好。

包命名

比函数更高一层的就是包，如何对包进行更好的命名也有一些经验

只由小写字母组成，不包含大写字母和下划线等字符
简短并包含一定的上下文信息。例如schema、task等
不要与标准库同名。例如不要使用sync或者strings
不适用常用变量名作为包名。例如使用bufio而不是buf
使用单数而不是复数。例如使用encoding而不是encodings
谨慎地使用缩写。例如使用fmt在不破坏上下文的情况下比format更加简短

小结

核心目标是降低阅读理解代码的成本
重点考虑上下文信息，设计简洁清晰的名称
Good naming is like a good joke. If you have to explain it, it's not funny.

2.4 控制流程

避免嵌套，保持正常流程清晰
- 如样例所示，如果两个分支中都包含return语句，则可以去除冗余的else
```
// Bad
if foo {
    return x
} else {
    return nil
}

//Good
if foo {
    return x
}
return nil
```

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

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

// Bad
func OneFunc() error {
    err := doSomething()
    if err == nil {
        err := doAnotherThing()
        if err == nil {
            return nil
        }
        return err
    }
    return err
}

调整后

// Good
func OneFunc() error {
    if err := doSomething(); err != nil {
        return err
    }
    if err := doAnotherThing(); err != nil {
        return err
    }
    return nil
}

小结

正常流程代码沿着屏幕向下移动
故障多出现在复杂的条件语句和循环语句中

2.5 错误和异常处理

简单错误

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

示例

func defaultCheckRedirect(req *Request, via []*Request) error {
    if len(via) >= 10 {
        return errors.New("stopped after 10 redirects"
    }
    return nil
}

错误的Wrap和Unwrap

对于复杂的错误，有时候并不能简单描述，应该如何处理呢？

错误的Wrap（包装）实际上是提供了一个error嵌套另一个error的能力，从而生成一个error的跟踪链，同时结合错误的判定方法来确认调用链中是否有关注的错误出现。这个能力的好处是每一层调用方可以补充自己对应的上下文，方便跟踪排查问题，确定问题的根本原因在哪里。
在fmt.Errorf中使用：%w 关键字来将一个错误关联至错误链中

示例

list, -, err := c.GetBytes(cache.Subkey(a.actionID, "srcfiles"))
if err != nil {
    return fmt.Errorf("reading srcfiles list:%w", err)
}

错误判定

判定一个错误是否为特定错误，使用errors.Is

不同于使用==，使用该方法可以判定错误链上的所有错误是否含有特定的错误

示例

data, err = lockedfile.Read(targ)
if errors.Is(err, fs.ErrNotExist) {
    return []byte{},nil
}
return data, err
}

在错误链上获取特定种类的错误，使用errors.As，它和is的区别在于as会提取出调用链中指定类型的错误，并将错误赋值给定义好的变量，方便后续显示

示例

if _, err := os.Open("non-existing"); err != nil {
    var pathError *fs.PathError
    if errors.As(err, &pathError) {
        fmt.Println("Failed at path:", pathError.path)
    } else {
        fmt.Println(err)
    }
}

panic

在Go中，比错误更严重的就是panic，它的出现表示程序无法正常工作了，那么在使用时需要注意什么呢？

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

下面示例是启动消息队列监听器的逻辑，在创建消费组失败的时候会Panicf，实际打印日志，然后抛出panic

func main() {
    // ...
    ctx, cancel := context.WithCancel(context.Background())
    client, err := sarama.NewConsumerGroup(strings.Split(brokers,","), group, config)
    if err != nil {
        log.Panicf("Error creating consumer group client: %v", err)
    }
    // ...
}

// Panicf is equivalent to Printf() followed by a call to panic().
func Panicf(format string, v ... interface{}) {
    s := fmt.Sprintf(format, v...)
    std.Output(2,s)
    panic(s)
}

recover

有panic，自然就会提到recover，因为我们不能控制所有的代码，避免不了引入其他库，如果是引入库的bug导致panic，影响到我自身的逻辑该如何处理？

recover只能在defer的函数中使用
嵌套无法生效
只在当前goroutine生效
defer的语句是后进先出
- 通过下面代码来理解defer是后进先出的
```
func main() {
    if true {
        defer fmt.Printf("1")
    } else {
        defer fmt.Printf("2")
    }
    defer fmt.Printf("3")
}
```
  程序的输出是什么？
  - defer语句会在函数返回前调用
  - 多个defer语句是先进后出
  - 最终输出：31

如果需要更多的上下文信息，可以在recover后再log记录当前的调用栈

示例是debug.Stack()包含的调用堆栈信息，方便定位具体代码问题

func (t *treeFS) Open(name string) (f fs.File, err error) {
    defer func() {
        if e := recover(); e != nil P
            f = nil
            err = fmt.Errorf("gitfs panic: %v\n%s", e, debug.Stack())
        }
    }()
    // ...
}

小结

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

总结

前面的代码格式、命名规范是现在能够去做好的，而后面的控制流程和错误异常处理，基本没怎么接触过，听得云里雾里，得到后面慢慢体会。

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