Go注释规范要求单行注释//置于代码上方，禁用行尾注释；多行注释/ /仅用于包说明或调试，不可替代godoc；函数/结构体注释须用顶格//块且无空行；包注释须在doc.go中以// Package开头。
单行注释必须写在代码上方或右侧，不能写在行末干扰阅读
Go 社区普遍接受的实践是：单行注释 // 优先放在被注释代码的正上方，而非行尾。虽然语法允许 a := 1 // 初始化计数器 这种写法，但一旦逻辑变复杂（比如带条件、嵌套或长表达式），行尾注释会严重拉宽代码行、破坏对齐，也容易和后续修改脱节。
- ✅ 推荐位置：函数定义前、变量声明前、关键分支前
- ❌ 避免滥用：不要为
if true { ... }或return nil这类显而易见的语句加行尾注释 - ⚠️ 坑点：IDE 自动格式化（如
gofmt）不会调整行尾注释位置，但多人协作时极易因缩进不一致导致注释“漂移”到错误逻辑旁
多行注释只用于包说明或临时屏蔽代码，别用它写函数文档
/* ... */ 在 Go 中有明确分工：它不是 godoc 的目标注释形式。Go 工具链（包括 go doc 和 VS Code 插件）默认只提取以 // 开头、紧贴声明上方的注释生成文档。用 /* */ 写函数说明，等于主动放弃自动生成文档的能力。
- ✅ 合理用途：在
doc.go中写包级说明；调试时临时注释掉一段逻辑 - ❌ 错误用法：给
func ServeHTTP(...)加/* 处理 HTTP 请求 */—— 这段注释不会出现在go doc net/http#ServeHTTP输出里 - ⚠️ 坑点：
/* */无法嵌套，若内部已有/*，再套一层会直接编译失败；而//无此限制，更安全
函数和结构体注释必须用 // + godoc 格式，否则 IDE 不识别
VS Code 的 Go 扩展、GoLand 的参数提示、go doc 命令，全部依赖「紧邻声明上方的连续 // 注释块」。这个块最好包含函数作用、参数含义、返回值说明，甚至示例（用 // Example: 开头会被 godoc 特殊处理）。
// Add 计算两个整数之和。
// 参数：
// a: 被加数
// b: 加数
// 返回值：
// int: 和
// Example:
// sum := Add(2, 3) // sum == 5
func Add(a, b int) int {
return a + b
}- ✅ 必须顶格写，且与函数定义之间**不能有空行**（否则
godoc视为断开） - ✅ 参数/返回值用冒号分隔，保持垂直对齐可读性更高
- ⚠️ 坑点：如果注释里混了
/*或漏了空行，VS Code 悬停时可能只显示“no documentation found”
包注释要单独放在 doc.go，且必须是 // 开头
一个包只能有一个权威包注释，它应该解释包的用途、设计意图、典型用法，而不是罗列所有导出函数。Go 工具要求这个注释必须出现在 package xxx 声明的正上方，且推荐放在独立的 doc.go 文件中——这样避免业务文件被注释“撑大”，也方便统一维护。
立即学习“go语言免费学习笔记（深入）”；
// Package mathutil 提供基础数学工具函数。 // // 本包不依赖外部库，所有函数均为纯函数。 // 典型用法： // result := mathutil.Max(10, 20) package mathutil
- ✅ 包注释必须以
// Package xxx开头，否则go doc不识别为包级文档 - ✅ 支持空行分段，但每行仍需以
//起始（不是/* */） - ⚠️ 坑点：如果在多个
.go文件里都写了包注释，go doc只取第一个遇到的，其余被忽略——容易造成信息不一致
真正难的不是写注释，而是让注释和代码一起活下来：函数签名改了，参数名变了，注释里还写着旧名字；包重构拆分后，doc.go 忘记同步更新。这些地方没有语法报错，但会悄悄腐蚀团队的理解成本。
