go注释是源码组成部分，必须用//单行紧贴声明上方，禁用/ /块注释和空行；字段需逐行注释，gomment+配置文件保障ci级一致性。
Go 代码注释不是“可有可无的说明”，而是 go doc、gopls 悬停提示、revive 静态检查直接依赖的源码组成部分。配置错一个空行或用错注释符号，文档就丢；字段没注释，revive 就报 exported field X should have comment。
Go 注释必须用 // 单行，且紧贴声明上方
Go 不识别 /* */ 块注释作为文档注释，也不允许函数/方法注释和声明之间插入空行。
- ✅ 正确：
// Add returns the sum of a and b.后紧跟func Add(...) - ❌ 错误：在
// Add...前加空行 →go doc完全跳过该函数 - ❌ 错误：写成
/* Add returns... */→gopls不解析，IDE 悬停无提示 - ⚠️ 注意：注释末尾带句号时，前面必须有空格，如
// Add .会被误判为句子结束，影响后续参数解析（尤其含代码示例时）
Goland 中配置文件级注释模板（新建 .go 文件自动填充）
路径：File → Settings → Editor → File and Code Templates → Files → Go File
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 填入标准包级注释模板（注意：必须放在
package xxx上方，且整个项目仅允许一个）：
// Package ${GO_PACKAGE_NAME} provides ...
// It handles ...
// Author: ${USER}
// Date: ${DATE} ${TIME}
-
${GO_PACKAGE_NAME}会自动替换为当前文件所在目录名（需与go.mod中模块路径一致） - 不要手动写
package main在模板里——Goland 会自动生成，模板只管注释部分 - 如果团队强制英文文档，此处禁用中文，避免
go doc输出乱码
Goland 中配置函数/结构体/接口的 Live Template（快捷键触发）
路径：File → Settings → Editor → Live Templates → + → Live Template，缩写建议设为 gf（go func）或 gs（go struct）
- 模板内容示例（函数）：
// ${DESCRIPTION:prompt}
// @param ${PARAMS}
// @return ${RETURNS}
func ${NAME}(${PARAMS}) ${RETURNS} {
- 点击
Edit variables，为DESCRIPTION设默认值TODO，PARAMS和RETURNS勾选Skip if defined - 在
Applicable contexts中只勾选Go，避免污染其他语言 - 结构体模板必须每字段单独一行注释，不能合并：
// Name is the display name.+Name string，否则revive报错
团队统一用 gomment + 配置文件落地规范
本地 IDE 配置易丢失，真正保障一致性的是命令行工具 + 版本化配置文件。
- 安装：
go install github.com/omriz/gomment@latest（注意：不是go get，新版 Go 推荐go install） - 项目根目录放
gomment.toml，内容示例：
[Comments] struct_header = "// %v (type %v) represents ..." field = "// %s %s" func = "// %s(%s) %s\n//\n// @param ...\n// @return ..."
- CI 流程中加入：
gomment add -config gomment.toml ./... || exit 1，未按模板注释的代码直接阻断合并 - 关键点：gomment 不覆盖已有注释，只补空缺——所以必须先清理历史不规范注释，再首次运行
最易被忽略的是结构体字段注释的粒度：每个导出字段必须独立占一行 //，哪怕只是 // ID int，也不能省略；而字段间绝不能空行，否则后一个字段的注释会被解析器当成前一个字段的延续。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
