高质量编程｜ 青训营

高质量编程

高质量编程是指以高标准和规范进行软件开发，以产生可靠、可维护、可扩展和高效的代码。

• 可读性优先： 代码应该易于阅读和理解，变量名、函数名应该具有表意性。选择具有描述性的变量、函数和类名，使其能清晰地表达其用途和功能。避免使用含糊不清或者过于简短的命名。
• 编码规范：编码规范是一组约定俗成的规则，用于统一代码的风格和结构。遵循一致的命名约定、缩进风格、注释规范等，可以使代码易读易懂，并减少错误。
• 简洁明了： 避免冗余代码，使用合适的数据结构和算法，让代码尽可能简洁，同时保持功能完整。
• 注重性能： 在保持代码可读性的前提下，考虑算法的效率和性能。避免不必要的循环和重复计算。
• 注释解释： 代码中应添加适量的注释，解释代码的意图、实现思路和关键步骤。这有助于其他开发者理解和维护代码。
• 模块化设计： 将代码拆分成小的、可复用的模块，提高代码的可维护性和可测试性。
• 错误处理： 考虑异常情况和边界条件，进行适当的错误处理，避免潜在的问题。使用适当的异常处理机制，例如try-catch语句，以及记录和报告异常信息。
• 版本控制： 使用版本控制系统（如Git）来管理代码的变更和版本历史，方便回溯和团队协作。
• 文档化：为代码编写清晰、易懂的文档，包括函数和类的说明、接口定义、用法示例等。良好的文档可以帮助其他开发人员理解和使用你的代码。
• 性能优化：对关键的代码进行性能优化，提高程序的执行效率。使用合适的数据结构和算法，避免不必要的资源消耗，如内存泄漏和过度的循环。

针对go语言中，具体来说

• 格式：

  • 使用 gofmt 自动格式化代码，使得Go代码符合官方统一风格。

• 注释：

  • 应解释的内容：（1）代码作用 （2）代码实现过程 （3）代码实现的原因，如适合代码的外部因素（上下文）等（4）代码的限制条件
  • 公共符号始终要注释，比如变量、常量、函数以及结构，公共功能必须，函数必须。

• 命名规范：核心目标是降低阅读理解代码的成本

  • 简洁
  • 缩略词全大写，变量开头且不需要导出时全小写。

  • 变量距离其被使用的地方越远（更需要辨认含义），则需要携带越多的上下文信息。而for循环中写i最好，写index就不好。提供外部调用的函数形参命名不要省略意义，deadline比t好。

    • 函数：

      • 函数不携带包名的上下文信息，引文包名和函数名总是成对出现的
      • 函数名尽量简短
      • 包名和包中函数返回类型相同时，可以省略类型信息而不导致歧义，返回其他类型可以在函数名中加入类型信息

    • 包：

      • 只有小写字母组成，不包含大写字母和下划线等字符
      • 简短且包含一定上下文信息
      • 不要与标准库同名
      • 尽量不适用常用变量名作为包名
      • 尽量使用单数而不是负数
      • 谨慎使用缩写

    • 控制流程：

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

错误和异常处理

• 简单错误：只出现一次的错误 优先使用匿名变量：errors.New
• 如果有格式化的需求，使用fmt.Errorf

• 错误的 Wrap和Unwrap wrap是错误的嵌套，生成error的跟踪链。%w关键字关联一个错误至错误链。fmt.Errorf("reading srcfiles list: %w", err)

• 错误判定

  • errors.Is判断是否指定类型error:errors.Is(err, fs.ErrNotExist)
  • errors.As取出特定种类错误:errors.As(err,&pathError)

• panic

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