Go语言必知必会100问题-15 缺少代码文档

缺少代码文档

文档（代码注释）是编码的一个重要方面，它可以降低客户端使用API的复杂度，也有助于项目维护。在Go语言中，我们应该遵循一些规则使得我们的代码更地道。下面一起来看看这些规则。

每个可导出的元素必须添加文档说明，无论是结构体、接口、函数还是其他元素。如果它被导出，则必须有文档说明。通用的文档说明是添加注释，注释前以元素名称开始，像下面这样。

// Customer is a customer representation.
type Customer struct{}
 
// ID returns the customer identifier.
func (c Customer) ID() string { return "" }

按照惯例，每条注释都应该是一个以 . 标点符号结尾的完整句子。此外，当对一个函数（或方法）注释说明时，应该强调函数打算做什么，而不是它是如何实现的。函数实现的功能、目的才是属于函数和注释的核心。理想情况下，文档注释应该提供足够的信息，使得使用者不必查看源码即可了解如何使用导出的元素。

弃用元素

可以使用 // Deprecated: 注释来弃用导出的元素。像下面这样，当开发人员再调用 ComputePath 函数时，会收到警告信息(大多数IDE不推荐使用弃用的元素)。

// ComputePath returns the fastest path between two points.
// Deprecated: This function uses a deprecated way to compute
// the fastest path. Use ComputeFastestPath instead.
func ComputePath() {}

当对变量或常量进行注释说明时，我们可能想传递两方面内容：它的目的和内容. 变量或常量的目的应该作为代码文档存在，以便对外部使用者有所帮助。但是变量或常量的内容不一定需要被使用者看到。例如下面的代码。DefaultPermission 表示默认权限，代码文档注释说明了该变量的目的，而常量旁边的注释描述了它的实际内容（读写权限）。

// DefaultPermission is the default permission used by the store engine.
const DefaultPermission = 0o644 // Need read and write accesses.

为了能够让程序的使用者和维护人员了解包的范围，还应该给包添加文档说明。按照惯例，注释以 //Package 开头，后面跟Package名称：

// Package math provides basic constants and mathematical functions.
//
// This package does not guarantee bit-identical results
// across architectures.
package math

包的第一行注释应该简洁，因为它将出现在包的文档中。如下图所示，每个包名后的简洁说明来自包中文档的第一行说明。

可以在任何Go文件中编写包文档，没有规则限制。通常，我们应该将包文档放在与包同名的相关Go文件中，或者放在特定文件中，如doc.go. 关于包文档，最后要说的一点是，与声明不相邻的注释会被省略。例如，下面的版权注释在生成的Go文档中不可见。

// Copyright 2009 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 math provides basic constants and mathematical functions.
//
// This package does not guarantee bit-identical results
// across architectures.
package math

总之，我们应该记住，每个导出的元素都需要有文档说明。代码注释文档说明不应该成为一种约束，相反，我们应该充分利用它，确保通过它能够帮助程序使用者和维护人员理解代码用途。