高质量编程及编码规范笔记|豆包MarsCode AI刷题

1.1 简介

什么是高质量

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

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

1.1.1 编程原则

简单性

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

可读性

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

生产力

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

1.2 编写规范

如何编写高质量的Go代码

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

公共符号始终要注释

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

 // Read implements the io.Reader interface
 func(r *FileReader) Read(buf []byte) (int, error)

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

gofmt

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

goimports

也是Go语言官方提供的工具

实际上等于gofmt加上依赖包管理

自动增删依赖的包引用、将依赖包按字母顺序排序并分类

1.2.2 编码规范-注释

简介

• 注释应该做的

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

小结

• 代码是最好的注释
• 注释应该提供代码未表达出的上下文信息

1.2.3 编码规范-命名规范

变量

• 简洁胜于冗长

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

  • 例如使用ServeHTTP而不是ServeHttp
  • 使用XMLHTTPRequest或者xmlHTTPRequest

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

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

function

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

package

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

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

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

小结

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

1.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 := null{
           err := doAnotherThing()
           if err == nil{
               return nil// normal case
           }
           return err
       }
       return err
   }

上述代码的问题在于：

• 最常见的正常流程的路径被嵌套在两个if条件内
• 成功的退出条件是return nil，必须仔细匹配大括号来发现
• 函数最后一行返回一个错误，需要追溯到匹配的左括号，才能了解何时会触发错误
• 如果后续正常流程需要加一步操作，调用新的函数，则又会增加一层嵌套。

上述代码的改进：

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

小结

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

1.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

  Go1.13在errors中新增了三个新API和一个新的format关键字，分别是errors.is errors.As，errors.Unwrap以及fmt.Errorf的%w。如果项目运行在小于Go1.13版本中，导入golang.org/x/xerrors来使用。

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

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

  错误判定

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

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

     data, err = lockedfile.Read(targ)
     if errors.Is(err, fs.ErrNotExist){
         // Treat non-existent as emppty, to bootstrap the "latest" file
         // the first time we connect to a given database
         return []byte{}, nil
     }
     return data, err
    

  • 在错误链上获取特定种类的错误，使用errors.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

  • 不建议在业务代码中使用panic

  • 调用函数不包含recover会造成程序崩溃

  • 若问题可以被屏蔽或解决，建议使用error代替panic

  • 当程序启动阶段发生不可逆转的错误时，可以在init或main函数中使用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

  • recover只能在被defer的函数中使用

  • 嵌套无法生效

  • 只在当前goroutine生效

  • defer的语句是后进先出

     func (s *ss) Token(skipSpace bool, f func(rune) bool)
     (tok []byte, err error){
         defer func(){
             if e := recover(); e != nil{
                 if se, ok := e.(scanError); ok{
                     err = se.err
                 }else{
                     panic(e)
                 }
             }
         }()
         // ...
     }
    

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

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

  小结

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