day3 编码规范 | 青训营笔记

yeyr2
61 阅读5分钟

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

1.什么是高质量编程:

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

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

2.编程原则

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

减少难以理解的代码,让其他程序员可以维护,能清晰明确的知道代码的功能.

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

确保其他人可以看懂代码,在其他人阅读项目代码时,可以减少阅读代码的时间.

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

3.编码规范

1.注释

公共符号始终要注释

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

注释作用:

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

解释代码的作用:

  • 适合注释公共符号

解释代码如何做的

  • 适合注释实现过程

解释代码实现的原因

  • 适合解释代码的外部因素(如:为什么要这么做)
  • 提供额外上下文(包括代码未表达出的)

解释代码什么情况会出错

  • 适合解释代码的限制条件

2.代码格式

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

  • gofmt : Go语言官方提供的工具,能自动格式化Go语言代码为官方统一风格
  • foimports : Go语言官方提供的工具,实际等于gofmt加上依赖包管理,自动增删依赖的包引用,将依赖包按字母序排序并分类

3.命名规范

variable

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

function

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

例子:http包中创建服务的函数如何命名更好

func Serve(I net.Listener,handler Handler) error
func ServeHTTP(I net.Listener,handler Handler) error

倾向于第一种,因为包名中已经含有部分信息

package

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

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

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

命名规范核心目的是为了降低阅读理解代码的成本.

控制流程

  • 避免嵌套,保持正常流程清晰
  • 经历保持正常代码路径为最小缩进
  • 优先处理错误/特殊情况,尽早返回或者继续循环来减少嵌套

减少嵌套可以将判断语句提前,将程序主体放在if语句之外. 例如使用:

func main() {
   resp, err := http.Get("https://www.baidu.com")
   if err != nil {
      log.Fatalln(err)
   }
   defer resp.Body.Close()
   if resp.StatusCode != http.StatusOK {
      log.Fatalln(err)
   }
   var doc *html.Node
   doc, err = html.Parse(resp.Body)
   if err != nil {
      log.Fatalln(err)
   }
   visit(doc)
   //io.Copy(os.Stdin, resp.Body)
}

而不是

func main() {
   resp, err := http.Get("https://www.baidu.com")
   if err == nil {
      defer resp.Body.Close()
      if resp.StatusCode != http.StatusOK {
         log.Fatalln(err)
      }
      var doc *html.Node
      doc , err = html.Parse(resp.Body)
      if err == nil {
         visit(doc)
       //io.Copy(os.Stdin, resp.Body)
      }
      log.Fatalln(err)
   }
   log.Fatalln(err)
}

使用了更少的嵌套,可以使代码读起来更清晰

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

错误和异常处理

简单错误
  • 简单错误是指仅出现一次的错误,且其他地方不需要捕获该错误
  • 优先使用errors.New来创建匿名变量来直接表示简单错误
  • 如果有格式化的需求,使用fmt.Errorf
错误的Wrap和Unwarp
  • 错误的Warp实际上是提供了一个error嵌套另一个error的能力,从而生产一个error的跟踪链
  • 在fmt.Errorf中使用%W关键字来将一个错误关联至错误链中
错误判断
  • 判断一个错误是否为特定错误,使用error.ls
  • 不同于使用==,使用该方法可以判定错误链上的所有错误是否含有特定错误.
data ,err := lockedfile.Read(targ)
if errors.Is(err,fs.ErrNotExist) {
   return []byte{},nil
}
return data,err
  • 在错误链上获取特定种类的错误,可使用errors.As,例如:
_, err := http.Get("https://www.baiddsfasdu.com")
var path *fs.PathError
if errors.As(err, &path) {
   fmt.Println(path.Path)
}else {
   fmt.Println(err)
}
panic
  • 不建议在业务代码中使用panic
  • 调用函数不包括recover会造成程序崩溃
  • 若问题可以被屏蔽或解决,建议使用error或者panic
  • 当程序启动阶段发生不可逆转的错误,可以在init或者main函数中使用panic
recover
  • recover只能在被defer的函数中使用
  • 嵌套无法生效
  • 只能在当前goroutine生效
  • defer的语句是后进先出的
  • 如果需要更多的上下文信息,可以recover后在log中记录当前的调用栈.

详细recover和panic可以看books.studygolang.com/gopl-zh/ch5…

avatar
文章
阅读
粉丝