Go 文档：编写不言自明的代码

为什么 Go 中的文档是超能力，而不是无聊的义务

想象一下：你打开一个别人的 Go 项目，里面——一个注释都没有。函数名叫 f1、f2，结构体叫 Data 和 MoreData。熟悉吗？如果是，那你知道热情是如何迅速转变为关闭仓库的冲动的。

Go 是一种崇尚简洁和清晰的语言。但即使是最干净的代码，有时也无法不言自明。Go 中良好的文档不仅仅是给同事的“善意姿态”。它是一个专业的工具，可以：

\n
• 加速新开发者的入职流程；
\n
• 帮助避免错误（你还记得吗，注释可以防止 API 被错误使用？）；
\n
• 自动在 pkg.go.dev 上生成漂亮的页面；
\n
• 提高代码质量（试着给一个糟糕的函数写注释——你自己都会想重写它）。
\n

在本文中，我们将探讨 Go 项目文档化的最佳实践。从 godoc 的基本规则到你今天就能应用的真实示例。我们开始吧！

Go 文档的哲学：言简意赅

Go 不是 Java，也不是 Python。这里没有人会写多页的 Javadoc 或 20 行的 docstring。Go 的哲学很简单：文档化行为，而不是实现。

在官方指南 Effective Go 中明确说明：注释应该描述代码做什么，而不是怎么做。如果你的代码复杂到需要解释算法——也许它应该被简化。

基本原则：

\n
• 注释是一个句子。以函数或类型的名称开头。// Calculate returns the result of the calculation.——很好。// This function calculates...——失去了重点。
\n
• 用英语写。Go 是一种国际化语言，英语文档是事实上的标准。但如果你的项目严格针对俄语团队，也可以用俄语。关键是保持一致性。
\n
• 不要解释显而易见的事情。// SetName sets the name——毫无用处。最好这样：// SetName updates the user's display name. Must be called before Save.
\n

Godoc：你最好的朋友和自动文档生成器

Go 自带内置工具 godoc。它直接从代码中解析注释并创建 HTML 文档。这意味着你的文档与代码共存——并且同时更新。

它是如何工作的？非常简单。在导出的实体（函数、类型、结构体、常量）之前直接编写注释——godoc 就会拾取它。

基础包示例：

// Package calculator provides basic arithmetic operations.\npackage calculator\n\n// Add returns the sum of two integers.\nfunc Add(a, b int) int {\n    return a + b\n}\n\n// Subtract returns the difference of two integers.\nfunc Subtract(a, b int) int {\n    return a - b\n}

现在运行 godoc -http :8080 并打开浏览器。你会看到一个漂亮的页面，包含包和每个函数的描述。魔法！

godoc 的良好行为准则

\n
• 始终注释包。包注释是用户首先看到的内容。它应该描述包的用途，理想情况下，包含一个使用示例。
\n
• 不要忘记类型和结构体。如果结构体的字段从名称上看不明显，也要为它们编写文档。
\n
• 使用空行。godoc 将第一段视为简短描述，其余部分视为详细信息。用空行将它们分开。
\n

// User repre