10.1.1 为什么需要代码规范

  1. 代码规范不是强制的，也就是你不遵循代码规范写出来的代码运行也是完全没有问题
  2. 代码规范的目的是方便团队形成一个统一的代码风格，提高代码的可读性，规范性和统一性。本规范将从命名规范，注释规范，代码风格和Go语言提供的常用的工具这几个方面做一个说明。
  3. 规范并不是唯一的，也就是说理论上每个公司都可以制定自己的规范，不过一般来说整体上规范差异不会很大

    10.1.2 代码规范

    命名规范

    命名是代码规范中很重要的一部分，统一的命名规则有利于提高代码的可读性，好的命名仅仅通过命名就可以获取到足够多的信息。
  • 当命名（包括常量、变量、类型、函数名、结构字段等等）以一个大写字母开头，如Group1，那么使用这种形式的标识符的对象就可以被外部包的代码所使用（客户端程序需要先导入这个包），这被称为导出（像面向对象语言中的public）;
  • 命名如果以小写字母开头，则对包外是不可见的，但是他们在整个包的内部是可见并且可用的（像面向对象语言中的private）

    包名 package

    保持package的名字和目录保持一致，尽量采取有意义的包名、简短、有意义尽量和标准库不要冲突。包名应该为小写单词，不要使用下划线或者混合大小写。
    1. packge model
    2. package main

    文件名

    尽量采取有意义的文件名，简短、有意义、应该为小写单词、使用下划线分割各个单词
    1. user_model.go

结构体命名

  • 采用驼峰命名法，首字母根据访问控制大写或者小写
  • struct 申明和初始化格式采用多行，例如下面
  1. type User struct {
  2.     Username string
  3.     Email    string
  4. }
  6. //多行初始化
  7. u := User{
  8. Username: "wozen"
  9. Email: "wjajeff@qq.com"
  10. }

接口命名

  • 命名规则基于和上面的结构体类型

  • 单个函数的结构以“er”作为后缀，例如Reader、Writer

    1. type Reader interface{
    2.   Read(p []byte)(n int, err error)   
    3. }

    变量命名

  • 和结构体类型，变量名称一般遵循驼峰法，首字符根据访问控制原则大写或者小写，但遇到特有名词时，需要遵循以下规则

    • 如果变量为私有，且特有单词为首个单词，则使用小写，如apiClient
    • 其他情况都应当使用该名词原有的写法，如APIClient、repoID、UserID
    • 错误示例：UrlArray，应该协程urlArray 或者URLArray
    • 若变量类型为bool类型时，则名称应以Has,Is,Can或Allow开头
      1. var isExist bool
      2. var hasConflict bool
      3. var canManage bool
      4. var allowGitHook bool

      常量命名

      常量均需使用全部大写字母组成，并使用下划线分词
  1. const APP_VER = "1.0"

如果是枚举类型的常量，需要先创建相应类型

  1. type Scheme string
  2. const (
  3.     HTTP Scheme = "http"
  4.     HTTPS Scheme = "https"
  5. )

注释

程序员最不喜欢的两件事

  1. 自己写注释
  2. 别人不写注释

注释目的： 写清楚 代码函数的目的 描述大概思路 以及具体的每个变量的含义 注释写的号 可能比代码写的好更重要 a //a表示xxx 这段代码目的其实是因为业务造成了很奇怪的逻辑 不论是你自己还是别人来看这段代码都会莫名奇妙 这也是为什么老程序员不敢随便改别人的代码的原因 包分三类： go语言自带的包 go get 安装的第三方包 自己写的common

Go提供C风格的/* */块注释和C++风格的//注释。行注释是常态；块注释主要显示位包注释，但在表达式中很有用或禁用大量代码。

  • 单行注释是最常见的注释形式，你可以在任何地方使用以 //开头的单行注释
  • 多行注释也叫块注释，均以/*开头，并以*/结尾，且不可以嵌套使用，多行注释一般用于包的文档描述或注释成块的代码片段。

go语言自带的godoc工具可以根据注释生成文档，生成可以自动生成对应网站（golang.org此处链接到时候换成国内镜像站就是用godoc工具直接生成的），注释的质量决定了生成的文档的质量。每个包都应该有一个包注释，在package子句之前有一个块注释。对于多文件包，包注释只需要存在于一个文件中，任何一个都可以。包评论应该介绍包，并提供与整个包相关的信息。它将首先出现在godoc页面上，并应设置下面的详细文档。

包注释

每个包都应该有一个包注释，一个位于package子句之前的块注释或行注释。包如果有多个go文件，只需要出现在一个go文件中（一般是和包同名的文件）即可。包注释应该包含下面基本信息（请严格按照这个顺序，简介，创建人，创建时间）：

  • 包的基本简洁（包名，简介）
  • 创建者，格式：创建人：rtx名
  • 创建时间，格式：创建时间：yyyyMMdd
    1. // util包，该包包含了项目共用的一些常量，封装了项目中的一些共用函数。
    2. // 创建人：hanru
    3. // 创建时间：20190419

    结构（接口）注释

    每个自定义的结构体或者接口都应该有注释说明，该注释对结构进行简要介绍，放在结构体定义的前一行，格式为：结构体名，结构体说明。同时结构体内的每个成员变量都要有说明，该说明放在成员变量的后面（注意对其），实例如下：
  1. // User： 用户对象 定义了用户的基础信息
  2. type User struct{
  3.     Username string //用户名
  4.     Email string //邮箱
  5. }

函数（方法）注释

每个函数、方法（结构体或者接口下的函数称为方法）都应该有注释说明，函数的注释应该包括三个方面（严格按照此顺序撰写）：

  • 简要说明，格式说明：以函数名开头，“，”分隔说明部分
  • 参数列表：每行一个参数，参数名开头，“，”分隔说明部分
  • 返回值：每行一个返回值 ```go // NewAttrModel: 属性数据层操作类的工厂方法 // 参数： // ctx:上下文信息 // 返回值： // 属性操作类指针 func NewAttrModel(ctx common.Context)AttModel{

}

  1. <a name="Mi0Ok"></a>
  2. ### 代码逻辑注释
  3. 对于一些关键位置的代码逻辑，或者局部较为复杂的逻辑，需要有相应的逻辑说明，方便其他开发者阅读该段代码，实例如下：
  4. ```go
  5. // 从 Redis 中批量读取属性，对于没有读取到的 id , 记录到一个数组里面， 准备从DB中读取
  6. xxxx
  7. xxxx
  8. xxxx

注释风格

统一使用中文注释，对于中英文字符之间严格使用空格分隔，这个不仅仅是中文和英文之间，英文和中文标点之间也都要使用空格分隔，例如

  1. // 从 Redis 中批量读取属性，对于没有读取到的id,记录到一个数组里面，准备从 DB 中读取

上面Redis、id、DB 和其他中文字符之间都是用来空格分隔。

  • 建议全部使用单行注释

  • 和代码规范一样，单行注释不要过长，禁止超过120字符

    10.1.3 import规范

    import在多行的情况下，go import 会自动帮你格式化，但是我们这里还是规范一下import 的一些规范，如果你在一个文件里面引入了一个package，函数建议采用如下格式：

    1. import(
    2.   "fmt"
    3. )

    如果你的包引入了三种类型的包，标准库包，程序内部包，第三方包，建议采用如下方式进行组织你的包：

    1. import(
    2.   "encoding/json"
    3.   "strings"
    5.   "myproject/models"
    6.   "myproject/controller"
    7.   "myproject/utils"
    9.   "github.com/astaixe/beego"
    10.   "github.com/go-sql-driver/mysql"
    11. )

    有顺序的引入包，不同的类型采用空格分离，第一种是标准库，第二是项目包，第三是第三方包。在项目中不要使用相对路径引入包： ```go // 这是不好的导入 import “../net”

// 这是正确的做法 import “github.com/repo/proj/src/net”

  1. 但是如果引入本项目中的其他包，最好使用相对路径。
  2. <a name="wkJPb"></a>
  3. # 10.1.4 错误处理
  5. - 错误处理的原则就是不能丢弃任何有返回`err`的调用，不要使用`_` 丢弃，必须全部处理。接收到的错误，要么返回`err`，或者使用`log`记录下来
  6. - 尽早return：一旦有错误发生，马上返回
  7. - 尽量不要使用panic，除非你知道你在做什么
  8. - 错误描述如果是英文必须为小写，不需要标点结尾
  9. - 采用独立的错误流进行处理
  10. ```go
  11. //错误写法
  12. if err != nil{
  13.     //error handing
  14. } else {
  15.     //normal code    
  16. }    
  18. //正确写法
  19. if err != nil {
  20.     //error handing
  21.     return //or continue etc.
  22. }