青训营Day3 高质量编程｜ 青训营笔记

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

高质量编程

编程原则

什么是高质量？正确可靠、简洁清晰！

1. 正确性：是否考虑各种边界条件，错误的调用是否能够处理；
2. 可靠性：异常情况或者错误的处理策略是否明确，依赖的服务出现异常是否能够处理；
3. 简洁：逻辑是否简单，后续调整功能或新增功能是否能够快速支持；
4. 清晰：其他人是否能够理解。

编码规范

代码格式

gofmt工具自动格式化代码； goimports自动增删依赖的包引用，并按照字母排序分类。

注释

1. 应该解释代码作用；
2. 应该解释复杂逻辑实现过程；
3. 应该解释代码实现的原因（提供额外上下文）；
4. 应该解释代码潜在的限制条件和无法处理的情况；
5. 代码是最好的注释。

命名规范

1. 变量
   • 简洁胜于冗长
   • 缩略词全大写，但其位于变量开头且不需要导出时，使用全小写；
     • 例如使用 ServeHTTP 而不是 ServeHttp
     • 使用 XMLHTTPRequest 或者 xmlHTTPRequest
   • 变量距离被使用到的地方越远，则需要携带越多的上下文信息。比如全局变量在名字中需要更多的上下文信息
2. 函数命名
   • 函数名不携带包名，因为包名和函数名总是成对出现；
   • 函数名尽量简短；
3. 包名
   • 只有小写字母，不包含大写字母和下划线等字符；
   • 简短并包含一定的上下文信息。例如 schema，task 等；
   • 不要与标准库同名。例如不要使用 sync 或者 strings。

控制流程

1. 避免深层嵌套；
2. 尽量保持正常代码为最小缩进。

错误和异常处理

1. 简单错误
   • 简单错误是仅出现一次的错误，且在其他地方不需要捕获该错误；
   • 优先使用 errors.New 创建匿名变量来直接表示简单错误；
   • 如果有格式化的需求，使用 fmt.Errorf。
2. 错误的 wrap 和 unwrap
   • 错误的 wrap 实际上是提供了一个 error 嵌套另一个 error 的能力，从而生成一个 error 的跟踪链；
   • 在 fmt.Errorf 中使用: %w 关键字来将一个错误关联至错误链中。
3. 错误判定
   • 判定一个错误链上是否含有特定的错误，使用 errors.Is；
   • 使用 errors.As 来获取某种特定种类的错误，方便后续处理。
4. panic
   • panic 一般不在业务代码中使用；
   • panic 发生后会向上传播到调用堆栈，如果当前 goroutine 中所有 defered 函数都不包含 recover 就会造成整个程序奔溃；
   • 如果问题可以被解决，建议使用 error 代替 panic；
   • 当程序启动阶段发生不可逆转的错误时，可以在 init 或 main 函数中使用 panic。
5. recover
   • recover 只能在被 defer 的函数中使用；
   • 嵌套无法生效；
   • 只在当前 goroutine 生效；
   • 如果需要更多的上下文信息，可以 recover 后再 log 中记录当前调用栈。