Go函数注释必须紧贴声明、首行为“// 函数名 ”（含空格），多行均用//，末句号前需空格；参数返回值语义须自然融入正文，禁用@param；工具函数须详述边界、错误、空值及复杂度；//go:generate不可混入函数注释；函数名拼写须与代码完全一致。
函数注释必须紧贴声明且以函数名开头
go doc 和 IDE（如 VS Code + gopls）只识别紧贴函数声明上方、无空行隔开的 // 注释，且首行必须是 // 函数名 （注意末尾空格），否则文档丢失、hover 提示为空。
- 错误写法：
// 处理用户登录、// Login handler、// FuncLogin—— 工具链完全忽略 - 正确写法：
// Login后紧跟空格和完整句子，如// Login handles user login request. - 多行注释必须全部用
//，不能混用/* */；末尾句号前必须有空格，// Login .会破坏解析
参数和返回值说明要写在函数注释里，不单独加行内注释
Go 不支持像 Java 的 @param 标签，所有语义信息必须自然融入 Doc 注释正文。工具链不解析“参数：”“返回值：”这类标记，但人读得清、IDE 能提取关键字段。
- 推荐结构：首句讲功能，次句讲关键参数隐含逻辑（如 “
timeoutmust be > 0”），末句讲返回值含义或常见错误（如 “returnsErrNotFoundif key doesn’t exist”） - 避免冗余：“本函数用于…”“该方法会…”——直接说行为，例如
// RetryHTTP calls the endpoint up to maxRetries times, backing off exponentially. - 若参数名易歧义（如
id string是 UUID 还是数据库自增 int？），必须在注释中明确类型语义，而非只写 “ID”
工具函数尤其要注意错误枚举和边界条件说明
工具函数（如 ParseDuration、JoinPath、TrimPrefix）被复用频繁，调用方无法看实现，全靠注释判断是否安全。漏掉一个边界情况，就可能在线上 panic 或静默失败。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 必须列出所有可能返回的导出错误变量，例如
returns ErrInvalidDuration if s contains invalid time units - 对空输入、零值、nil 指针等做显式说明，如
// JoinPath returns empty string if paths is nil or empty - 性能敏感的工具函数（如字符串处理）可注明复杂度，例如
// TrimPrefix runs in O(n) and allocates only when prefix matches
别把 //go:generate 当普通注释写在函数上方
//go:generate 是特殊指令，不是文档注释。如果把它和函数 Doc 注释混在一起，会导致 go doc 解析失败——工具链会把整段当作函数文档，而它实际不属于该函数语义。
- 错误位置：
//go:generate mockgen -source=auth.go -destination=mock_auth.go紧挨着某个func Login上方 - 正确做法：放在文件顶部（包声明前）、或独立一行放在包级变量/常量之后，与任何函数保持至少一个空行
- 生成命令本身不参与文档，但它的存在意味着该包依赖外部代码生成——注释里可以加一句
// See //go:generate directives for auto-generated mocks and stringers.引导读者
真正容易被忽略的是：函数名拼写必须和代码定义逐字符一致，包括大小写和下划线。写成 // login（小写）或 // LoginUser（多写了 User），go doc 就认不出这是哪个函数的文档——它不 fuzzy match，只 exact match。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
