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 文件中——这样避免业务文件被注释“撑大”，也方便统一维护。

// Package mathutil 提供基础数学工具函数。
//
// 本包不依赖外部库，所有函数均为纯函数。
// 典型用法：
//   result := mathutil.Max(10, 20)
package mathutil

• ✅ 包注释必须以 // Package xxx 开头，否则 go doc 不识别为包级文档
• ✅ 支持空行分段，但每行仍需以 // 起始（不是 /* */）
• ⚠️ 坑点：如果在多个 .go 文件里都写了包注释，go doc 只取第一个遇到的，其余被忽略——容易造成信息不一致

真正难的不是写注释，而是让注释和代码一起活下来：函数签名改了，参数名变了，注释里还写着旧名字；包重构拆分后，doc.go 忘记同步更新。这些地方没有语法报错，但会悄悄腐蚀团队的理解成本。