go官方推荐用//写单行注释，/ /几乎不用；文档注释必须是紧贴导出标识符上方、无空行的//注释，首句为带句号的完整句子且≤80字符，后续可补充参数等说明但禁用markdown。
Go 里 // 和 /* */ 哪个该用？
Go 官方只推荐用 // 写单行注释，/<em> </em>/ 在实际项目中几乎不用——它不支持嵌套，且 go fmt 会把块注释自动转成多行 //，容易引发格式争议。文档注释（即导出标识符上方的注释）必须是 // 开头的连续单行，否则 godoc 不识别。
- 导出函数/类型/变量前必须有
//注释，且首句要能独立作摘要（比如被 IDE 悬停显示） - 包级注释写在
package xxx上方，用//，且必须是纯文本，不能含空行或/<em> </em>/ - 别在代码中间用
/<em> </em>/“注释掉一段逻辑”来临时调试——用if false { ... }更安全，也避免误提交
函数文档注释怎么写才被 godoc 正确解析？
godoc 只认紧贴在导出标识符正上方、无空行隔开的 // 注释。只要中间插了个空行，或者注释里混了非 ASCII 字符（如中文标点全角空格），解析就断了。
- 注释第一行必须是完整句子，结尾带句号，长度建议 ≤ 80 字符（IDE 悬停显示会截断）
- 后续行可补充参数说明、返回值、panic 条件等，但不要用 Markdown 语法（
godoc不渲染） - 示例：
// ParseTime parses a time string in RFC3339 format. // It returns an error if s is empty or malformed. func ParseTime(s string) (time.Time, error) { ... } - 别写
// ParseTime: parses...——冒号后少个空格，godoc就可能当成“命令式标题”而忽略后续描述
什么时候该写注释？什么时候不该写？
Go 强调“代码即文档”，注释不是补救烂代码的创可贴。如果某个逻辑需要注释才能看懂，优先考虑重命名变量、拆分函数、或加类型约束。
- 必须写：违反直觉的边界处理（比如
len(b) == 0时返回非空切片）、绕过标准库的 hack（如手动处理 UTF-8 首字节）、调用外部副作用（如修改全局状态或文件系统） - 禁止写：重复代码语义的废话，比如
// increment i by 1跟着i++ - 警惕“过期注释”：重构函数签名后忘了改上面的注释，比没注释更危险——它会误导人
注释里的代码示例怎么写才靠谱？
godoc 支持从注释中提取可运行示例（需匹配 func ExampleXXX()），但日常文档注释里的内联示例也有讲究。
- 示例代码必须能直接复制进
main.go运行（包括 import、func main()或完整调用链） - 避免使用未导出标识符（如
http.serveMux），否则示例失效 - 别写
// output: hello却不提供对应输出断言——读者没法验证对错 - 如果示例依赖网络或文件，加一句
// This example requires network access.，否则 CI 里跑go test -run=Example会挂
真正难的不是写注释，是判断哪一行代码值得让人多看一眼。很多团队花时间订规范，却没人回头看去年写的注释是否还准确。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
