高质量编程简介及编码规范 ｜ 青训营

hongjr03
49 阅读4分钟

高质量编程简介

高质量

编写的代码正确可靠、简洁清晰即高质量。

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

编程的原则

  • 简单性

    • 以简单清晰的逻辑编写代码
    • 不理解的代码无法修复改进

  • 可读性

    • 确保代码可读才能保证可维护

  • 生产力

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

编码规范

代码格式

推荐使用 Go 提供的 gofmt 自动格式化代码。

goimports 也是Go提供的工具，相当于 gofmt 加上依赖包管理，自动增删依赖包的引用、将依赖包按字母序排序分类。

现代 IDE 如 GoLand 均提供这些工具。

注释

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

— Dave Thomas & Andrew Hunt

  • 解释代码作用

    • 适合注释公共符号的作用。

  • 注释应该解释代码是如何做的

    • 适合注释实现过程。

  • 注释应该解释代码实现的原因

    • 适合解释代码的外部因素，可提供额外上下文。

  • 注释应该解释代码什么情况会出错

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

公共符号始终要注释

  • 包括变量、常量、函数以及结构，只要是公共符号都需要添加注释；
  • 不明显或不简短的公共功能必须予以注释；
  • 库中任何函数都必须进行注释。

例外：不需要注释实现接口的方法。

小结

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

命名规范

variable

  • 简洁 > 冗长

  • 缩略词处于变量开头且不需要导出时全小写，否则全大写

    • 例：ServeHTTP //ok ServeHttp //not ok
    • 例：XMLHTTPRequest / xmlHTTPRequest //both are ok

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

function

  • 函数名不携带包名的上下文信息（成对出现）
  • 函数名尽量简短
  • 当名为foo的包中某个函数返回类型为Foo时，可以省略类型信息
  • 当名为foo的包中某个函数返回类型不为Foo时，可以在函数名中加入类型信息

package

  • 只由小写字母组成
  • 简短且包含一定上下文信息
  • 不与标准库重名

同时还有以下规则尽量满足：

  • 不适用常用变量名作为报名
  • 使用单数而非复数
  • 选择性地使用缩写

小结

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

Good naming is like a good joke. If you have to explain it, it’s not funny.

— Dave Cheney

控制流程

  • 避免嵌套，保持正常流程清晰
// Bad
if foo {
    return x
} else {
    return nil
}
​
// Good
if foo {
    return x
}
return nil

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

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

小结

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

错误和异常处理

简单错误

指只出现一次的错误，且其他地方不需要捕获该错误。

  • 优先使用errors.New来创建匿名变量以直接表示简单错误
  • 如果有格式化的需求，使用fmt.Errorf

错误的Wrap和Unwrap

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

错误判定

  • 判定一个错误是否为特定错误，使用errors.Is
  • 不同于使用==，使用该方法可以判定错误链上的所有错误是否含有特定的错误
  • 在错误链上获取特定种类的错误，使用errors.As

panic

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

recover

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

小结

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