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

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

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

使用 gofmt

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

gofmt gofile.go

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

gofmt -w gofile.go

命名约定

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

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

    1
    2
    var foo := "bar" // 被导出
    var foo := "bar" // 不能被导出
  • 对于包含多个单词的变量命名可以使用驼峰法或帕斯卡写法,具体哪种写法,取决于变量是否需要导出

    1
    2
    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 生态系统广泛接受的约定

1
2
3
4
5
6
7
const Foo string = "constant string"

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

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

1
2
3
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,只需要用标准注释对代码进行注释,并遵守一些简单的约定即可。要给一段代码添加注释,需要在注释开头指出要注释的元素的名称。如下示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
//该代码示例了如何使用 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的效果:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
> 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
一种实现两个整数相减的函数, 返回值为两整数相减之差

go doc -all test

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

godoc

工作流程自动化

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

一个 Makefile 的文件示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 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 运行环境

golint 运行环境

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

goland 添加快捷键

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

golang golint 执行结果

问题列表

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

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