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

课堂笔记

本堂课重点内容

• 如何进行注释
• 如何优化循环与判断

详细知识点介绍

• 对变量名、函数名、包名的注释要点
• 对于函数的注释
• 优化循环判断

简介

编写的代码能够达到正确可靠、简洁清晰的目标可称之为高质量代码

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

编程原则

实际应用场景千变万化，各种语言的特性和语法各不相同

但是高质量编程遵循的原则是相通的

• 简单性

  • 消除“多余的复杂性”，以简单清晰的逻辑编写代码
  • 不理解的代码无法修复改进

• 可读性

  • 代码是写给人看的，而不是机器
  • 编写可维护代码的第一步是确保代码可读

• 生产力

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

编码规范

如何编写高质量的Go代码

• 代码格式
• 注释
• 命名规范
• 控制流程
• 错误和异常处理

注释

公共符号始终要注释

• 包中声明的每个公共的符号 变量、常量、函数以及结构 都需要添加注释

• 任何既不明显也不简短的公 共功能必须予以注释

• 无论长度或复杂程度如何， 对库中的任何函数都必须进 行注释

例外

• 不需要注释实现接口的方法，下面的方法是错误的

 // Read implements the io.Reader interface
 func (r *FileReader) Read(buf []byte) (int,error)

• 注释应该做的

  • 注释应该解释代码作用

    • 注释公共符号

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

    • 比如返回值，接收值的意义

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

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

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

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

命名规范

variable

• 简洁胜于冗长

• 缩略词全大写，但当其位于变量开头且不需要导出时，使用全小写

  • 例如使用ServeHTTP而不是ServeHttp
  • 使用XMLHTTPRequest或者xmIHTTPRequest

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

  • 全局变量在其名字中需要更多的上下文信息，使得在不同地方可以轻易辨认出其含义

• 举例

  • 将deadline替换成t降低了变量名的信息量
  • t常代指任意时间
  • deadline指截止时间，有特定的含义

 // Good
 func (c*Client) send(req*Request,deadline time.Time){}
 //Bad
 func (c*Client) send(req*Request,t time.Time){}

function

• 函数名不携带包名的上下文信息，因为包名和函数名总是成对出现的
• 函数名尽量简短
• 当名为foo的包某个函数返回类型Foo时，可以省略类型信息而不导致歧义
• 当名为foo的包某个函数返回类型T时(T并不是Foo)，可以在函数名中加入类型信息

package

• 只由小写字母组成。不包含大写字母和下划线等字符

• 简短并包含一定的上下文信息。例如schema、task等

• 不要与标准库同名。例如不要使用sync或者strings

  • 以下规则尽量满足，以标准库包名为例
  • 不使用常用变量名作为包名。例如使用bufio而不是buf
  • 使用单数而不是复数。例如使用encoding而不是encodings
  • 谨慎地使用缩写。例如使用fmt在不破坏上下文的情况下比format更加简短

控制流程

• 避免嵌套，保持正常流程清晰

  • 如果两个分支中都包含return语句，则可以去除冗余的else

     //Bad
     if foo{
         return x
     } else{
         return nil
     }
     //Good 
     if foo {
         return x
     }
     return nil
    

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

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

  • 举例

    • 最常见的正常流程的路径被嵌套在两个if条件内

    • 成功的退出条件是return nil,必须仔细匹配大括号来发现

    • 函数最后一行返回一个错误，需要追溯到匹配的左括号，才能了解何时会触发错误

    • 如果后续正常流程需要增加一步操作，调用新的函数，则又会增加一层嵌套

       //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
       } 
      

实践练习例子

课后个人总结

• 包名的注释
• 对于循环与判断的优化