go语言注释仅支持//和/ /两种语法，doc comment须以//紧贴导出标识符正上方，首句为完整句子且零空行，否则go doc无法解析；注释不能替代清晰命名与逻辑重构。
Go 语言注释没有“规范教程”这回事——官方只定义了两种合法语法，其余全是团队约定。
怎么写单行和多行注释
Go 只认 // 和 /* */，没有 /// 或文档生成专用的 /** */（那是其他语言的惯性思维）。// 后面所有内容直到行尾都是注释；/* */ 可跨行，但不能嵌套。
- 函数内部逻辑说明用
//，轻量、直观、不干扰结构 -
/* */仅用于临时屏蔽大段代码，或极少数需要跨行解释的边界场景（比如复杂正则表达式） - 别在
/* */里写长篇说明——go doc 不解析它，IDE 也不高亮，纯靠人肉读
什么时候该写 doc comment（即 // 前导注释）
只有以 // 开头、紧贴在 func/type/const/var 声明**正上方**的注释，才会被 go doc 提取。它不是“可选加分项”，而是公开 API 的说明书。
- 导出标识符（首字母大写）必须配 doc comment，否则
go doc pkg.Name查不到说明 - 非导出标识符（小写字母开头）可以不写，写了也不会出现在生成文档里
- 第一行建议是完整句子，以被注释名开头：“
ParseTimeparses a time string…” 而不是 “Parses a time string…” - 空行分隔摘要与详细说明，避免粘连成一段
godoc 解析规则和常见失效原因
go doc 和 godoc 工具对注释位置极其敏感，错一行就丢文档。
- doc comment 必须与声明之间**零空行**：上面是注释，下面是
func Foo()，中间不能有空行 - 不能混用
/* */写 doc comment——哪怕你写在函数正上方，go doc直接无视 - 如果包里有多个同名标识符（比如不同文件都定义了
ErrInvalid），doc comment 只会显示第一个匹配项 - 使用
go doc -all可查未导出项的注释，但普通go doc默认只看导出项
注释不是替代清晰命名和拆分逻辑的借口
遇到“这里得加注释说明为什么这么写”，先问自己：是不是变量名太模糊？是不是这个函数干了三件事？是不是错误处理路径藏得太深？
-
// 处理失败情况这类注释毫无信息量，不如把err != nil改成if !isValid(input) { - 注释里出现“TODO”“FIXME”“HACK”是危险信号——它们不该长期存在，更不该代替重构
- 接口方法的 doc comment 如果要解释“调用者必须保证输入非空”，说明这个约束应该由类型系统承担（比如用自定义类型封装非空字符串）
真正难的不是语法，是判断哪行代码值得注释、哪行该被重写。注释一旦写下去，就和代码一样需要维护——过期注释比没注释更误导人。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
