这是我参与「第三届青训营 -后端场」笔记创作活动的的第2篇笔记。 主要介绍如何编写高质量的代码。

一 什么是高质量的代码？

高质量的代码通常正确可靠、简洁清晰，一般具有以下三个特点：
1 简单性  尽量以简单清晰的逻辑编写代码，方便后续修改
2 可读性  编写可维护的代码第一步是确保代码可读
3 生产力  团队整体工作效率非常重要

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

编写高质量的代码可以从下面5个方面来考虑

2.1 代码格式

代码格式方面主要是注意缩进、空格、括号等
下面两个函数的编写都是正确的，但是add函数显然更赏心悦目一些
合理的使用空格和缩进可以让代码更加易读

func add (num1, num2 int) int {
   return num1 + num2
}

func sub(num1,num2)int{
   return num1-num2
}

2.2 注释

好的注释应该具有以下特点，在合适的地方添加具有下面特点的注释信息
另外要注意代码本身是最好的注释，合理的命名可以显著增加代码的可读性

1 注释应该解释代码作用
    通常对函数做注释
2 注释应该解释代码如何做的
    通常注释某段具体代码
3 注释应该解释代码实现的原因
    通常注释某段具体代码，提供额外信息
4 注释应该解释代码什么情况会出错
    通常注释函数
5 公共符号始终要注释
    包中声明的公共符号、函数都要注释

2.3 命名规范

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

1 variable
- 简洁胜于冗长
    for index := 0; index < len(s); index++ {}
    for i := 0; i < len(s); i++ {}
    i和index的作用域范围仅限于for循环内部时，index的额外冗长几乎没有增加对程序的理解
    
- 缩略词全大写，但当其位于变量开头且不需要导出时，使用全小写
    使用ServeHTTP而不是ServeHttp
    使用XMLHTTPRequest或xmlHTTPRequest

- 变量距离其被使用的地方越远，则需要携带越多的上下文信息
    全局变量在其名字中需要更多的上下文信息，使得在不同地方可以轻易辨认出其含义
    

2 function
- 函数名不携带包名的上下文信息，因为包名和函数名总是成对出现的
    如使用http.Serve()而不是http.ServeHTTP()

- 函数名尽量简短
    如使用time.Now()而不是time.NowTime()

- 当名为 foo 的包某个函数返回类型 Foo 时，可以省略类型信息而不导致歧义
- 当名为 foo 的包某个函数返回类型 T 时（T 并不是 Foo），可以在函数名中加入类型信息

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

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

人们在阅读理解代码的时候也可以看成是计算机运行程序，
好的命名能让人把关注点留在主流程上，清晰地理解程序的功能，
避免频繁切换到分支细节，增加理解成本

小tips: 好的命名就像一个好笑话，如果你必须解释它，那就不好笑了

2.4 流程控制

1 避免嵌套，保持正常清晰流程，如果两个分支中都包含 return 语句，则可以去除冗余的 else

// bad
if foo {
    return x
} else {
    return nil
}
// good
if foo {
    return x
}
return nil

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

// bad
func Func() error {
  err := doSomething()
  if err == nil {
      err = doAnotherThing()
      if err == nil {
          return nil // normal case
      }
      return err
  }
  return err
}
// good
func Func() error {
  if err := doSomthing(); err != nil {
      return err
  }
  if err := doAnotherThing(); err != nil {
      return err
  }
  return nil
}

显然后者更加易读，这提示我们处理逻辑尽量走直线，
避免复杂的嵌套分支，可以提高代码的可读性
故障大多出现在复杂的条件语句和循环语句中

2.5 错误和异常处理

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

return errors.New("error infomation")

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

return fmt.Errorf("some error infomation: %w", err)

3 错误判定
使用 errors.Is 可以判定错误链上的所有错误是否含有特定的错误。
如  if errors.Is(err, fs.ErrNotExist) {
        
    }

在错误链上获取特定种类的错误，使用 errors.As
如 var pathError *fs.PathError
   if errors.As(err, &pathError) {
       fmt.Println("failed at path:", pathError.Path)
   }

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

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

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

三 性能优化

1 预分配内存
在确定实际大小的情况下，预先分配空间

sli = make([]int, 0)           // bad
sli = make([]int, 0, size)     // good

for k := 0; k < size; k++ {
    data = append(data, k)
}


mp := make(map[int]int)         // bad
mp := make(map[int]int, size)   // good

for i := 0; i < size; i++ {
    mp[i] = 1
}

2 及时释放大内存
在已有切片上创建新切片，不会创建底层数组
在只有小切片引用底层数组时，底层数组不会释放，浪费内存
可使用copy进行深拷贝创建底层数组

func Func(origin []int) []int {
    return origin[len(origin)-2:]
}

func Func(origin []int) []int {
    result = make([]int, 2)
    copy(result, origin[len(origin)-2:])
    return result
}

3 字符串处理

func Plus(n int, str string) string {
    s := ""
    for i := 0; i < n; i++ {
        s += str
    }
    return s
}

func StringsBuilder(n int, str string) string {
    var builder strings.Builder
    for i := 0; i < n; i++ {
        builder.WriteString(str)
    }
    return builder.String()
}

func BytesBuffer(n int, str string) string {
    buf := new(bytes.Buffer)
    for i := 0; i < n; i++ {
        buf.WriteString(str)
    }
    return buf.String()
}

使用 + 拼接最慢，strings.Builder，bytes.Buffer相近
strings.Buffer最快
使用 + 每次都会重新分配内存
strings.Builder，bytes.Buffer底层都是[]byte数组
strings.Builder直接将底层的[]byte转化为字符串返回
bytes.Buffer转化为字符串时重新申请了一块空间

4 使用空结构体
空结构体不占用任何空间，仅作为占位符使用
如使用map[int]struct{}实现set

5 使用atomic
锁的实现是通过操作系统实现，属于系统调用
atomic操作是通过硬件实现，效率比锁高
sync.Mutex应该用来保护一段逻辑，而不仅仅保护一个变量
对于非数值操作，可使用atomic.Value，可以承载一个interface{}

四 性能调优

性能调优准则
1 要依靠数据而不是靠猜
2 要定位最大瓶颈而不是细枝末节
3 不要过早优化
4 不要过度优化


常见优化目标
1 业务优化
2 基础库优化
3 语言优化

总结

1 高质量的代码逻辑清晰、简洁易读、命名规范、格式优雅
2 避免常见的性能陷阱可以保证大部分程序的性能
  针对普通应用代码，不要一味地追求程序的性能
  越高级的优化手段越容易出现问题
  应当在满足正确可靠、简洁清晰等质量要求的前提下提高程序性能
3 进行性能优化时要定位最大的性能瓶颈而不是细枝末节