Go语言注释需紧邻声明上方无空行，包注释置于package语句前用/.../块注释，结构体字段与方法注释提升API可读性，godoc可本地启动服务实时预览文档。
Go语言的注释和文档系统简洁高效，关键在于遵循约定而非依赖复杂语法。只要注释写在正确位置、格式规范，godoc就能自动生成可读性强的文档，甚至支持Web查看。
注释必须放在声明上方，且紧邻不空行
Go只识别“前置式”注释：函数、变量、结构体、方法等的注释必须直接写在它们的上一行，中间不能有空行。否则godoc会忽略。
- ✅ 正确写法：
// Add returns the sum of a and b.
func Add(a, b int) int {
return a + b
}- ❌ 错误写法（空行或位置偏移）：
// This comment won't be picked up.
func Add(a, b int) int { ... }
// Also invalid: comment after declaration
func Add(a, b int) int { ... }
// This is too late.
包注释写在package语句前，用块注释更清晰
每个包应有一个简明扼要的包级说明，放在package xxx语句正上方。推荐使用/* ... */块注释，尤其当需要多行描述或强调用途时。
/* Package calculator provides basic arithmetic operations like addition, subtraction, and multiplication.It's designed for educational use and small-scale tools. */ package calculator
注意：包注释只需一份，放在任意一个.go文件顶部即可，不需要每个文件都重复。
立即学习“go语言免费学习笔记（深入）”；
结构体字段和方法也支持注释，提升API可读性
导出的结构体字段（首字母大写）如果加了注释，godoc会一并展示；方法同理。这对定义清晰的接口非常有用。
// User represents a registered user in the system.
type User struct {
// Name is the full name of the user.
Name string
// Age is the age in years; zero means unknown.
Age int
}
// Greet returns a friendly greeting message.
func (u User) Greet() string {
return "Hello, " + u.Name
}
用godoc本地启动文档服务，实时预览效果
安装后无需额外配置，直接运行命令即可生成本地文档站点：
- 查看当前包文档：
godoc -http=:6060，然后访问 https://www.php.cn/link/ed4e17d67f76e380e297298c8629c38d - 指定模块路径（如在项目根目录）：
godoc -http=:6060 -goroot=. - 终端中快速查某个函数：
godoc fmt Println
确保代码已保存，godoc会自动解析最新内容——改完注释刷新网页就能看到更新。
