高质量编程规范 | 青训营笔记

KumaLuv
78 阅读4分钟

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

高质量代码简介

首先，程序员都希望能写出高质量代码。所谓高质量代码，是指正确可靠，简介清晰的代码。其主要包括如下要点：

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

而通用的高质量编程原则如下：

  • 简单性：消除多余的复杂性，以简单清晰的逻辑编写代码，不能被理解的代码是无法得到修复改进的

  • 可读性：代码是给人看的，编写可维护代码的第一步是确保代码可读

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

高质量代码编写规范

代码格式

建议使用gofmt，自动化格式化Go语言代码为官方统一的风格；使用goimports加上依赖包管理，自动增加和删除依赖的包引用，将依赖包按字母排序。

注释

注释应该做到：

  • 解释代码作用：适合注释对象是公共符号

  • 解释代码实现的方法：适合注释实现过程

  • 解释代码实现的原因：适合解释代码的外部因素，提供额外的上下文

  • 解释什么时候代码出错：适合解释代码的限制条件

小结：代码是最好的注释，注释应该提供代码未表达出的上下文信息。公共符号始终要注释。包中声明的每个公共的符号，变量，常量，函数以及结构都需要添加注释，任何既不明显也不间断的公共功能必须予以注释，无论长度或复杂程度如何，对库中的任何函数都必须进行注释。例外是，不需要注释实现接口的方法。

命名规范

  • variable：简洁；缩略词全大写；变量距离被使用的地方越远，就需要携带越多的上下文信息，使得能在不同地方辨认出信息。

  • function：函数名不携带包名的上下文信息（因为包名和函数名总是成对出现的）；函数名尽量简短

  • package：只由小写字母组成，不包含大写字母和下划线；简短并包含一定的上下文信息；不要与标准库同名；不使用常用变量名作为包名；使用单数而不是复数；谨慎地使用缩写，尽量不破坏上下文的情况下保证尽可能简短。

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

控制流程

目标是避免嵌套，保持正常流程的清晰，保持正常代码的路径为最小缩进。

举例：

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

小结：线性原理，处理逻辑尽量走直线，避免复杂的嵌套分支，要提升代码可维护性和可读性。

错误和异常处理

  • error：仅仅出现一次的错误是简单错误，在其他地方不需要捕获，优先使用errors.New来创建匿名变量来直接表示简单错误，如果有格式化需求，使用fmt.Errorf。错误的wrap和unwarp，提供了一个error嵌套另一个error，生成一个error的跟踪链。errrors.Is可以判定错误是否为特定错误，errors.As可以在跟踪链上获取特定种类错误。

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

  • recover：使用时只能被defer的函数中使用，嵌套无法生效，只在当前goroutine中生效，如果需要更多上下文信息，可以recover后在log中记录当前的调用栈。

小结：error尽可能提供简明的上下文信息链，方便定位问题 ，panic用于真正异常的情况，recover注意生效范围

avatar
文章
阅读
粉丝