Question

我们已经学到如何用 go 这个通用工具进行编译和执行。但这个好用的工具还有很多其他没有介绍的诀窍。

3.5.1　 go vet

这个命令不会帮开发人员写代码，但如果开发人员已经写了一些代码， vet 命令会帮开发人员检测代码的常见错误。让我们看看 vet 捕获哪些类型的错误。

• Printf 类函数调用时，类型匹配错误的参数。
• 定义常用的方法时，方法签名的错误。
• 错误的结构标签。
• 没有指定字段名的结构字面量。

让我们看看许多 Go 开发新手经常犯的一个错误。 fmt.Printf 函数常用来产生格式化输出，不过这个函数要求开发人员记住所有不同的格式化说明符。代码清单 3-8 中给出的就是一个例子。

代码清单 3-8　使用 go vet

01 package main
02
03 import "fmt"
04
05 func main() {
06　　 fmt.Printf("The quick brown fox jumped over lazy dogs", 3.14)
07 }

这个程序要输出一个浮点数 3.14，但是在格式化字符串里并没有对应的格式化参数。如果对这段代码执行 go vet ，会得到如下消息：

go vet main.go

main.go:6: no formatting directive in Printf call

go vet 工具不能让开发者避免严重的逻辑错误，或者避免编写充满小错的代码。不过，正像刚才的实例中展示的那样，这个工具可以很好地捕获一部分常见错误。每次对代码先执行 go vet 再将其签入源代码库是一个很好的习惯。

3.5.2　Go 代码格式化

fmt 是 Go 语言社区很喜欢的一个命令。 fmt 工具会将开发人员的代码布局成和 Go 源代码类似的风格，不用再为了大括号是不是要放到行尾，或者用 tab（制表符）还是空格来做缩进而争论不休。使用 go fmt 后面跟文件名或者包名，就可以调用这个代码格式化工具。 fmt 命令会自动格式化开发人员指定的源代码文件并保存。下面是一个代码执行 go fmt 前和执行 go fmt 后几行代码的对比：

if err != nil { return err }

在对这段代码执行 go fmt 后，会得到：

if err != nil {
　　return err
}

很多 Go 开发人员会配置他们的开发环境，在保存文件或者提交到代码库前执行 go fmt 。如果读者喜欢这个命令，也可以这样做。

3.5.3　Go 语言的文档

还有另外一个工具能让 Go 开发过程变简单。Go 语言有两种方法为开发者生成文档。如果开发人员使用命令行提示符工作，可以在终端上直接使用 go doc 命令来打印文档。无需离开终端，即可快速浏览命令或者包的帮助。不过，如果开发人员认为一个浏览器界面会更有效率，可以使用 godoc 程序来启动一个 Web 服务器，通过点击的方式来查看 Go 语言的包的文档。Web 服务器 godoc 能让开发人员以网页的方式浏览自己的系统里的所有 Go 语言源代码的文档。

1．从命令行获取文档

对那种总会打开一个终端和一个文本编辑器（或者在终端内打开文本编辑器）的开发人员来说， go doc 是很好的选择。假设要用 Go 语言第一次开发读取 UNIX tar 文件的应用程序，想要看看 archive/tar 包的相关文档，就可以输入：

go doc tar

执行这个命令会直接在终端产生如下输出：

PACKAGE DOCUMENTATION

package tar // import "archive/tar"

Package tar implements access to tar archives．It aims to cover most of the
variations, including those produced by GNU and BSD tars.

References:

　　 http://www.freebsd.org/cgi/man.cgi?query=tar&sektion=5 
　　 http://www.gnu.org/software/tar/manual/html_node/Standard.html 
　　 http://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html 
var ErrWriteTooLong = errors.New("archive/tar: write too long") ...
var ErrHeader = errors.New("archive/tar: invalid tar header")
func FileInfoHeader(fi os.FileInfo, link string) (*Header, error)
func NewReader(r io.Reader) *Reader
func NewWriter(w io.Writer) *Writer
type Header struct { ..．}
type Reader struct { ..．}
type Writer struct { ..．}

开发人员无需离开终端即可直接翻看文档，找到自己需要的部分。

2．浏览文档

Go 语言的文档也提供了浏览器版本。有时候，通过跳转到文档，查阅相关的细节，能更容易理解整个包或者某个函数。在这种情况下，会想使用 godoc 作为 Web 服务器。如果想通过 Web 浏览器查看可以点击跳转的文档，下面就是得到这种文档的好方式。

开发人员启动自己的文档服务器，只需要在终端会话中输入如下命令：

godoc -http=:6060

这个命令通知 godoc 在端口 6060 启动 Web 服务器。如果浏览器已经打开，导航到 http://localhost:6060 可以看到一个页面，包含所有 Go 标准库和你的 GOPATH 下的 Go 源代码的文档。

如果图 3-2 显示的文档对开发人员来说很熟悉，并不奇怪，因为 Go 官网就是通过一个略微修改过的 godoc 来提供文档服务的。要进入某个特定包的文档，只需要点击页面顶端的 Packages。

图 3-2　本地 Go 文档

Go 文档工具最棒的地方在于，它也支持开发人员自己写的代码。如果开发人员遵从一个简单的规则来写代码，这些代码就会自动包含在 godoc 生成的文档里。

为了在 godoc 生成的文档里包含自己的代码文档，开发人员需要用下面的规则来写代码和注释。我们不会在本章介绍所有的规则，只会提一些重要的规则。

用户需要在标识符之前，把自己想要的文档作为注释加入到代码中。这个规则对包、函数、类型和全局变量都适用。注释可以以双斜线开头，也可以用斜线和星号风格。

// Retrieve 连接到配置库，收集各种链接设置、用户名和密码。这个函数在成功时
// 返回 config 结构，否则返回一个错误。
func Retrieve() (config, error) {
　　// ..．省略
}

在这个例子里，我们展示了在 Go 语言里为一个函数写文档的惯用方法。函数的文档直接写在函数声明之前，使用人类可读的句子编写。如果想给包写一段文字量比较大的文档，可以在工程里包含一个叫作 doc.go 的文件，使用同样的包名，并把包的介绍使用注释加在包名声明之前。

/*
　　包 usb 提供了用于调用 USB 设备的类型和函数。想要与 USB 设备创建一个新链接，使用 NewConnection
　　...
*/
package usb

这段关于包的文档会显示在所有类型和函数文档之前。这个例子也展示了如何使用斜线和星号做注释。可以在 Google 上搜索 golang documentation 来查找更多关于如何给代码创建一个好文档的内容。