Go语言中常见100问题-#15 Missing code documentation

数据小冰

发布于 2022-12-18 12:38:17

4130

缺少代码文档

文档（代码注释）是编码的一个重要方面，它可以降低客户端使用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

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

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2022-10-14，如有侵权请联系 cloudcommunity@tencent.com 删除

编程算法

本文分享自数据小冰微信公众号，前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

编程算法

登录后参与评论

0 条评论

热度