Go语言中常见100问题-#15 Missing code documentation
缺少代码文档
文档(代码注释)是编码的一个重要方面,它可以降低客户端使用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
总之,我们应该记住,每个导出的元素都需要有文档说明。代码注释文档说明不应该成为一种约束,相反,我们应该充分利用它,确保通过它能够帮助程序使用者和维护人员理解代码用途。
相关文章
- 实践GoF的设计模式:迭代器模式
- 【补充】Gitlab 部署 CI 持续集成
- Google Chrome 应用商店上传扩展程序
- 实践GoF的23种设计模式:观察者模式
- Ubuntu Docker 安装和配置 GitLab CI 持续集成
- Ubuntu 简单安装和配置 GitLab
- 二进制SCA指纹提取黑科技:Go语言逆向技术
- 解读Go分布式链路追踪实现原理
- 基于C#的MongoDB数据库开发应用(4)--Redis的安装及使用
- 基于C#的MongoDB数据库开发应用(3)--MongoDB数据库的C#开发之异步接口
- 基于C#的MongoDB数据库开发应用(1)--MongoDB数据库的基础知识和使用
- Linux 常用命令(持续补充)
- 云小课|3种常用Git工作流推荐
- 实践GoF的23种设计模式:装饰者模式
- git bisect:让你闭眼都能定位疑难 bug的利器
- 通用权限管理系统多语言开发标准接口 - java,php 调用标准接口程序参考
- 收到Sybase公司PowerDesigner产品的律师函后,只能改进一下思路了
- 实践GoF的设计模式:工厂方法模式
- 有了这10个GitHub仓库,开发者如同buff加持
- 【clickhouse专栏】对标mongodb存储类JSON数据文档统计分析