函数注释必须以函数名开头、紧贴声明上方、无空行、句号结尾，缺一不可；否则go doc和ide悬停完全不识别，90%失效源于空行、首句格式或标点错误。
必须以函数名开头、紧贴声明上方、无空行、句号结尾——缺一不可，否则 go doc 和 IDE 悬停完全不识别。
函数注释为什么总不显示在 godoc 或 VS Code 悬停里
90% 的失效原因是格式松动：注释和 func 之间插了空行、首句没以函数名开头、漏了英文句号、用了全角标点或中文空格。
-
go doc只认紧贴导出函数正上方、无任何间隔的//注释；中间哪怕一个空行，整个注释块就被跳过 - 首句必须是完整英文句子，且严格以函数名 + 空格起始，例如
// Login handles user login request.，不能写成// login handles...（小写）、// Login: handles...（冒号后少空格）、// Login handles...（缺句号） - 全角句号
。、中文空格、UTF-8 BOM、甚至注释行末尾多一个不可见空格，都会导致解析中断 - 如果函数签名改了（比如新增参数），但注释没同步更新，IDE 悬停会展示过期信息，比没注释更危险
func 前的注释要写什么、怎么组织
首句是摘要，≤80 字符，能独立作 IDE 悬停提示；后续行补充行为契约，不是写“本函数用于……”这类冗余话。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 首句说明「做什么」+「关键约束」，例如：
// ParseTime parses a time string in RFC3339 format. - 后续行说明参数隐含逻辑（如
s为空时 panic 还是返回 error）、返回值含义（尤其是自定义错误变量）、可能 panic 的条件 - 避免 Markdown、避免代码块、避免缩写（如用
HTTP不用http） - 若函数返回错误，显式列出可被
errors.Is(err, ErrInvalid)检查的变量，例如：// Returns ErrInvalid if s is empty or malformed.
结构体方法的注释和普通函数有区别吗
没有本质区别，但要注意接收者类型和方法名拼写必须与代码完全一致——大小写、下划线、驼峰全部敏感。
- 方法注释同样必须紧贴
func (r *Reader) Read(p []byte) (n int, err error)上方，无空行 - 首句以方法全名开头，例如：
// Reader.Read reads up to len(p) bytes into p.，不能省略接收者类型名Reader. - 如果方法属于接口实现，注释应聚焦该方法在接口契约中的语义，而非具体实现细节（比如不写「使用 bufio.Reader 缓冲」，而写「保证原子读取单个完整消息」）
- 导出方法（首字母大写）才需要文档注释；未导出方法（如
read）即使写了也不会被go doc提取
包里多个 .go 文件，注释该写在哪
只在一个文件顶部写包注释，且必须顶格、紧邻 package 声明前——其他文件留空，重复写反而容易因格式不一致导致失效。
- 包注释必须以
// Package <name></name>开头（<name></name>是实际包名，大小写严格匹配），结尾带英文句号 - 例如包名为
auth，就得写// Package auth implements JWT-based authentication.，不能写// package auth（小写）或// Package Auth（大写） - 包注释只能有一段，不能拆成两块
// Package auth...+// It supports...；中间插入空行或 HTML 标签也会让整段失效 - 如果项目用 Go modules，本地运行
godoc -http=:6060时需加-paths=.才能加载当前模块
最常被忽略的是：注释不是“写完就完”，而是源码的一部分——go vet 会检查导出标识符是否缺失注释，gopls 依赖它提供准确悬停，go test -cover 的覆盖率统计甚至会把未注释的导出函数标记为“文档缺口”。一旦松动格式，工具链就断链。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
