Go注释是可执行文档，需严格遵循格式：包注释顶格写于package前且仅一处，以“// Package xxx”开头、大小写匹配、结尾英文句号；函数/类型注释紧贴声明、首句完整；字段注释逐行独立、说明业务含义；空行和大小写错误将导致解析失效。
Go 的注释不是写给人看的补充说明，而是直接参与 go doc 解析、IDE 悬停提示、go vet 检查的可执行文档。写错格式，整块注释就失效——哪怕只多一个空行、少一个句号、大小写不匹配。
包注释必须顶格写在 package 前且仅一处
包注释决定整个包是否出现在 godoc -http=:6060 页面里。它不是“可选”，而是硬性入口。
- 必须写在
package xxx正上方，中间**不能有任何空行**（包括 HTML<p>、空白符、注释分隔线） - 必须以
// Package xxx开头，xxx大小写须与实际包名完全一致（如包是utils，就不能写Utils） - 结尾必须是英文句号（
.），不能用中文“。”或省略 - 整个项目只能在一个
.go文件中写包注释；其他文件顶部留空，重复写反而导致解析失败 - 若用 Go modules，
godoc默认不扫描当前目录，启动时得加-path=.
func 和 type 的 Doc 注释必须紧贴声明、首句完整
godoc 和 VS Code hover 只识别紧贴导出标识符（首字母大写）正上方、无空行、以函数/类型名开头的 // 注释。
- 首行必须是完整句子：
// Login handles user login request.（注意：Login后空格 + 动词开头 + 英文句号） - 不能写成
// login handles...（小写）、// Login: handles...（冒号后缺空格）、// Login handles（缺句号） - 后续行可写
// Args:、// Returns:、// Errors:，但不要用 Markdown，godoc不渲染 - 如果函数签名改了（比如新增参数），注释没同步更新，比没注释更危险——它会误导调用方
-
/* */块注释、或注释与函数之间插了var cache = sync.Map{}这类声明，整块注释直接被忽略
结构体字段注释必须逐行独立、说明业务含义
导出字段（首字母大写）没有注释，go vet 会报 exported field X should have comment；IDE 悬停也看不到字段语义。
立即学习“go语言免费学习笔记（深入）”；
- 每个字段前都要有单独的
//行，不能合并（如// ID int // Name string是错的） - 注释要具体：说明用途、约束、序列化行为，例如
// Email is the primary contact address. Required. json:"email" - 避免模糊描述：
// user email不如// Email is the verified primary contact, used for password reset and notifications. - 字段之间不能有空行，否则后一个字段的注释会被当成前一个字段的延续
- 小写字母开头的字段（非导出）即使写了注释，也不会出现在
go doc输出中
别把注释当补丁，该重构时别硬加
Go 强调“代码即文档”。需要长篇注释才能解释清楚的逻辑，大概率该拆函数、改命名、加类型约束，而不是堆注释。
- 必须写注释的场景：违反直觉的边界处理（如
len(b) == 0返回非空切片）、绕过标准库的 hack、修改全局状态或文件系统等副作用 - 禁止写注释的场景：重复代码语义（
// i++ → increment i by 1）、用中文标点全角空格、在代码中间用/* */“临时注释掉逻辑”（改用if false { }更安全） - 行内注释（
//）只解释“为什么”，不解释“是什么”；重点讲权衡、并发假设、性能敏感点 - 注释里的示例代码必须能直接复制进
main.go运行，不能依赖未导出标识符（如http.serveMux）
最常被忽略的其实是空行和大小写——它们不会报错，但会让整个注释链失效。写完记得跑一遍 godoc -http=:6060 -path=. 看是否真能加载出来。
