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 能提取关键字段。

• 推荐结构：首句讲功能，次句讲关键参数隐含逻辑（如 “timeout must be > 0”），末句讲返回值含义或常见错误（如 “returns ErrNotFound if 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语言免费学习笔记（深入）”；

• 错误位置：//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。