高质量编程

King Yen.

编写的代码正确可靠、简洁明了

---

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

---

编程原则

• 简单性
  • 消除“多余的复杂性”，以简单清晰的逻辑编写代码
  • 不理解的代码无法修复改进
• 可读性
  • 代码是写给人看的，而不是机器
  • 编写可维护代码的第一步是确保代码可读
• 生产力
  • 团队整体工作效率
  • 相似的代码风格

编码规范

1. 代码格式

• 使用 gofmt 自动格式化代码

• 注释

  注释的作用

  • 解释代码作用
    • 公共符号
  • 解释代码逻辑
    • 实现过程
  • 解释代码实现原因
    • 代码外部因素
    • 提供额外上下文
  • 解释代码什么情况下会出错
    • 代码的限制条件

  公共符号始终要注释

  • 包中声明的每个公公的符号：变量、常量、函数以及结构都需要添加注释
  • 任何极不明显也不明显也不简短的公共功能必须予以注释
  • 无论长度或复杂程度如何，对苦衷的任何函数都必须进行注释

  • Comment Sentences

2. 命名规范

1. 变量 variable
   • 简洁
   • 缩略词全部大写，担当起位于变量开头且不需要导出时，使用全小写
   • 变量距离其使用的地方越远，则需要携带越多的上下文信息
2. 函数 function
   • 函数名不懈怠包名的上下文信息，因为包名和函数名总是成对出现
   • 函数名尽量简短
   • 当名为 foo 的包某个函数返回类型 Foo 时，可以省略类型信息而不导致起义
   • 当名为 foo 的包某个函数返回类型 T 时，可以在函数名中加入类型信息
3. 包 package
   • 只由小写字母组成。不包含大写字母和下划线等字符
   • 简短并包含一定上下文信息
   • 不与标准库同名
   • 不使用常用变量
   • 使用单数而不是复数
   • 谨慎使用缩写

3. 控制流程

1. 避免嵌套，保证正常流程清晰

2. 尽量保成正常代码路径为最小缩进

   • 优先处理错误情况/特殊情况

     • 成功退出条件为 return nil，必须仔细匹配打括号
     • 函数最后一行返回的错误，需要最速到匹配的左括号才能了解何时触发
     • 后续正常流程需要增加一步操作，调用新的函数，则需要增加一层嵌套

     e.g.

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

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

4. 错误和异常处理

1. 简单错误

   仅出现一次且在其他地方不需要捕捉的错误

   • 优先使用 errors.New 来创建匿名变量直接表示简单错误
   • 使用 fmt.Errorf 进行格式化

2. Wrap & Unwrap

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

3. 错误判定

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

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

   • 在错误链上获取特定种类的错误，使用 errors.As

   • panic

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

   • recover

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