Go 语言系列35：编码规范

这一期我们谈一谈 Go 语言的 编码规范 。一个统一的代码风格有利于提高代码的可读性、规范性和统一性。首先声明一点，这里的编码规范并不代表官方，只是参考网络上的一些文章以及 Go 语言官方代码风格的制定进行整理。

命名

包命名

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

文件命名

1. 尽量采取有意义的文件名
2. 文件名应该简短且有意义
3. 由于 Windows 平台文件名不区分大小写，所以文件名命名应该统一为小写
4. 应该使用下划线分隔各个单词，而不是使用驼峰式命名
5. 测试文件以 _test.go 结尾
6. 文件如果具有平台特性，应以 文件名_平台.go 命名，例如 utils_windows.go 和 utils_linux.go ，可用平台有：windows, unix, posix, plan9, darwin, bsd, linux, freebsd, nacl, netbsd, openbsd, solaris, dragonfly, bsd, notbsd, android, stubs
7. 一般情况下应用主入口为 main.go 或者以应用的全小写形式命名

常量命名

1. 使用全大写且用下划线分隔各个单词，比如 APP_VERSION
2. 如果要定义多个常量，要使用 括号 来组织

const (
  APP_VERSION = "0.1.0"
  CONF_PATH = "/etc/xx.conf"
)

当然网上还有另一种命名风格，那就是使用驼峰命名法，但我个人并不推荐这种命名风格。

变量命名

1. 使用驼峰命名法
2. 在相对简单的环境（对象数量少、针对性强）中，可以将完整单词简写为单个字母，例如：user 写为 u
3. 首字母根据访问控制原则大写或者小写
4. 如果变量为私有，且特有名词为首个单词，则使用小写，例如：apiClient
5. 如果变量不是私有，但有特有名词，那首单词就要全部变成大写，例如：APIClient
6. 如果变量类型为 bool 类型，则名称应以 has 、 is 、 can 或 allow 开头，例如：isExist 、 canManage

结构体命名

1. 使用驼峰命名法
2. 首字母根据访问控制原则大写或者小写
3. struct 声明和初始化格式采用多行

// 多行声明
type Person struct {
 name string
 gender string
 age  int
}

// 多行初始化
person := Person{
    name: "John",
    gender: "male",
    age: 18,
}

接口命名

1. 使用驼峰命名法
2. 单个函数的结构名以 er 作为后缀，例如：Reader 、 Writer

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

函数命名

1. 使用驼峰命名法
2. 对于需要在包外访问的函数要以大写字母开头命名
3. 对于不需要在包外访问的函数要以小写字母开头命名

函数内部的参数的排列顺序也有几点原则：

• 参数的重要程度越高，应排在越前面
• 简单的类型应优先复杂类型
• 尽可能将同种类型的参数放在相邻位置，则只需写一次类型

注释

包注释

1. 每个包都应该有一个包注释，它位于 package 语句之前，可以是块注释或者行注释。如果一个包中有多个文件，则只需要在一个文件中编写，该文件一般是和包同名的文件
2. 包注释应该包含下面基本信息(严格按照下面的顺序，简介，创建人，创建时间)：

// 包的基本简介(包名，简介)
// 创建人:     name
// 创建时间:   yyyyMMdd

3. 如果是特别复杂的包，可单独创建 doc.go 文件说明
4. 如果你想在每个文件中的头部加上注释，需要在版权注释和 package 前面加一个空行，否则版权注释会作为 package 的注释

// Copyright 2010 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package fmt

结构体/接口注释

每个自定义的结构体或者接口都应该有注释说明，该注释对结构进行简要介绍，放在结构体定义的前一行，格式为：结构体名, 结构体说明 。

同时结构体内的每个成员变量都要有说明，该说明放在成员变量的后面(注意对齐)，例如：

// User ， 用户对象，定义了用户的基础信息
type User struct{
    Username  string // 用户名
    Email     string // 邮箱
}

函数/方法注释

每个函数或者方法都应该有注释说明，函数、方法和类型的注释说明都是一个完整的句子。

当然还有下面这种注释习惯，该函数注释包括三个方面(严格按照下面的顺序)：

// 函数名， 简要说明
// 参数：
//      参数1：参数说明
//      参数2：参数说明
// 返回值：
//      每行一个返回值

特别注释

TODO ：提醒维护人员此部分代码待完成

FIXME ：提醒维护人员此处有 BUG 待修复

NOTE ：维护人员要关注的一些问题说明

其他注意点

1. 所有导出对象都需要注释说明其用途；非导出对象根据情况进行注释
2. 如果对象可数且无明确指定数量的情况下，一律使用单数形式和一般进行时描述；否则使用复数形式
3. 句子类型的注释首字母均需大写；短语类型的注释首字母需小写
4. 注释的单行长度不能超过 80 个字符
5. 若函数或方法为判断类型(返回值主要为 bool 类型)，则以 <name> returns true if 开头

代码风格 

缩进和折行

1. 使用 tab 键进行缩进，或者直接使用 gofmt 工具格式化即可
2. 折行方面，一行最长不超过 120 个字符，超过的请使用换行展示

括号和空格

1. 在 Go 语言中一定要注意括号的放置位置，大括号不换行
2. 运算符和操作数之间要留空格

包的导入

1. 单个包导入直接 import 一行解决
2. 多个包导入，要使用 () 来组织
3. 根据包的来源，标准库要排最前面，第三方包次之、项目内的其它包和当前包的子包排最后，每种分类以一空行分隔
4. 不要使用相对路径来导入包

错误处理

1. 不能丢弃任何有返回 err 的调用，不要使用 _ 丢弃，必须全部处理
2. 接收到错误，要么返回 err ，或者使用 log 记录下来
3. 尽早 return ，一旦有错误发生，马上返回
4. 尽量不要使用 panic ，除非你知道你在做什么
5. 错误描述如果是英文必须为小写，不需要标点结尾
6. 采用独立的错误流进行处理

👇周一至周五更新，期待你的关注👇