[Go 入门] 第十三章 命名约定

Go 入门系列参考于互联网资料与 人民邮电出版社 《Go 语言入门经典》 与 《Effective Go》，编写目的在于学习交流，如有侵权，请联系删除

在 Go 语言生态系统, 应该会经常遇到 “Go 语言惯常方式（Idiomatic Go）” 一词，它指的是被普遍接受的行事方式, 本文内容:

• 使用 gofmt
• 命名约定
• 使用 golint
• 使用 godoc
• 工作流程自动化
  • 使用 Goland 配置 golint
• 问题列表

使用 gofmt

为确保按要求的约定设置 Go 代码的格式，Go 提供了gofmt。这个工具的优点在于，无需了解代码格式设置约定，使用工具 gofmt 来设置其格式，是其遵循代码格式设置约定。对文件运行 gofmt 时，将把结果打印到标准输出，但不修改原来的文件。

gofmt gofile.go

如果让其修改原来的文件加上

gofmt -w gofile.go

命名约定

据说在计算机科学中，最难的两件事是缓存和命名。虽然这种说法不能当真，但清晰的命名可提高代码的可读性和可维护性。在 Go 语言中，有些约定是编译器要求必须遵循的，而有些是否遵循由程序员决定。

• 以大写字母开头的标识符将被导出，而以小写字母则不会

  var foo := "bar" // 被导出
  var foo := "bar" // 不能被导出 

• 对于包含多个单词的变量命名可以使用驼峰法或帕斯卡写法，具体哪种写法，取决于变量是否需要导出

  var fileName //驼峰法
  var FileName //帕斯卡  

• 数据类型的简短命名如 i 表示整型 (Integer) , s 表示字符串数据类型

• 接口是具名的方法签名集合，一般在动词后面加上er，形成一个名词，如 Reader
• 对于导出的函数，应该通过包名函数名来访问，其次应注意使用 math.Sqrt 而不是 math.MathSqrt 这样的命名

使用 golint

golint 是 Go 语言提供的一个官方工具。gofmt 根据指定的约定设置代码的格式，而命令 golint 根据 Go 项目本身的约定查找风格方面的错误。默认不会安装 golint，但可像下面这样安装它

go get -u github.com/golang/lint/golint

随后在 GOPATH 目录下 切换到 ../src/github.com/golang/lint/golint

执行 go install，执行完成后，在 %GOROOT%/bin 下会生成一个 golint.exe

要核实是否正确地安装了这个工具，可在终端下执行命令 golint —help。如果正确地安装了，可在终端执行 golint —help。如果正确地安装了它，将在终端中看到一些帮助文本，工具 golint 提供了有关风格方面的提示，还可帮助学习 Go 生态系统广泛接受的约定

const Foo string = "constant string"

func main() {
    fmt.Println(Foo)
    a_string := "hello"
    fmt.Println(a_string)
}

这些代码能够通过编译，也能通过 gofmt 的检查。能够通过编译说明这些代码正确无误，能够通过 gofmt 的检查说明格式也没有问题。但是这些代码存在着一些风格方面的问题，有一个个变量包含下划线，使用工具 golint 可找出这种风格方面的问题，如检查上面的代码，将输出：

golint main.go
main.go:5:7: exported const Foo should have comment or be unexported
main.go:9:2: don't use underscores in Go names; var a_string should be aString

使用 godoc

随着要开发的程序越来越复杂， 要确保其品质优良，编写文档至关重要。即便单独开发，注释也有助于快速理解代码

godoc 是一款官方工具，可通过分析 Go 语言源代码及其中的注释来生成文档。由于文档是根据源代码生成的，真很大程度上避免了文档不同步（软件项目中的常见的问题）

虽然 godoc 是一款官方工具，但是它必须单独安装。

go get golang.org/x/tools/cmd/godoc

要核实是否正确安装了这款工具，可以执行 godoc --help，如果安装正确，则可以看到一串帮助文本。

如果使用过其他编程语言，那么您可能熟悉代码注释的约定。使用 godoc，只需要用标准注释对代码进行注释，并遵守一些简单的约定即可。要给一段代码添加注释，需要在注释开头指出要注释的元素的名称。如下示例：

//该代码示例了如何使用 godoc
package test

// 一种实现两个整数相加的函数，
// 返回值为两整数相加之和
func Add(a, b int) int {
	return a + b
}

// 一种实现两个整数相减的函数，
// 返回值为两整数相减之差
func Sub(a, b int) int {
	return a - b
}

// 一种实现两个整数相乘的函数，
// 返回值为两整数相乘之积
func Mul(a, b int) int {
	return a * b
}

// 一种实现两个整数相除的函数，
// 返回值为两整数相除之商
func Div(a, b int) int {
	if b == 0 {
		panic("divide by zero")
	}

	return a / b
}

因为从 go 1.12版本开始，godoc单纯的仅仅是个 web 服务器，我们需要使用go doc -all, 可以切换到当前包的路径下，执行即可输出之前go doc的效果：

> go doc -all test
warning: pattern "all" matched no module dependencies
package test // import "test"

该代码示例了如何使用 godoc

FUNCTIONS

func Add(a, b int) int
    一种实现两个整数相加的函数， 返回值为两整数相加之和

func Div(a, b int) int
    一种实现两个整数相除的函数， 返回值为两整数相除之商

func Mul(a, b int) int
    一种实现两个整数相乘的函数， 返回值为两整数相乘之积

func Sub(a, b int) int
    一种实现两个整数相减的函数， 返回值为两整数相减之差

之后，将 test 包赋值到 Go 安装目录下的 src 文件中，启用 godoc -http=localhost:6060，访问localhost:6060即可看到该包的 Html 说明文档

工作流程自动化

可以使用 Goland 等优秀的 IDE 可安装插件来实现工作流程自动话，如果使用的是 unix 系统还可使用 Makefile 可简化源代码编译、测试和检查工作

一个 Makefile 的文件示例：

# Go parameters
GOCMD=go
GOBUILD=$(GOCMD) build
GOCLEAN=$(GOCMD) clean
GOTEST=$(GOCMD) test
GOGET=$(GOCMD) get
BINARY_NAME=out
BINARY_UNIX=$(BINARY_NAME)_unix

all: test build
build:
        $(GOBUILD) -o $(BINARY_NAME) -v
test:
        $(GOTEST) -v ./...
clean:
        $(GOCLEAN)
        rm -f $(BINARY_NAME)
        rm -f $(BINARY_UNIX)
run:
        $(GOBUILD) -o $(BINARY_NAME) -v ./...
        ./$(BINARY_NAME)
deps:
        $(GOGET) github.com/markbates/goth
        $(GOGET) github.com/markbates/pop

使用 Goland 配置 golint

第一步，设置 golint 运行环境

随后在指定一个快捷键，例如 Alt+L

配置完成后，在 go 源码文件窗口，按下 Alt+L 便会自动执行 golint

问题列表

• 对于开发的开源 Go 项目，可将其文档托管在什么地方

  大多数托管网站都能分析 Go 代码，然后生成 Html 格式的文档。一个这样流程的网站是 GoDoc, 如何将包上传可参考 About