本篇基于 Go 1.25.1 版本，教会你标准注释写法、godoc 规范，让代码自带说明书，团队协作超顺畅✅
一、Go 注释两种形式（基础必学）
Go 提供单行注释和多行注释，语法简单，风格统一。
| 类型 | 符号 | 用法 |
|---|---|---|
| 单行注释 | // | 行内说明、简短解释 |
| 多行注释 | /* */ | 包说明、大段描述、函数注释 |
二、官方推荐注释规范
Go 官方有严格的注释风格，专业开发者必须遵守：
- 1. 注释与代码隔一个空格
- 2. 句子结尾加句号
- 3. 包、函数、结构体必须写文档注释
- 4. 注释用英文/中文清晰描述，不写废话
三、godoc 文档注释（最重要！）
godoc 是 Go 官方文档工具，规范注释 = 自动生成 API 文档。
1. 包注释（package 上方）
放在 package 上，说明包的作用、用途。
// Package user 提供用户模块相关功能，包含用户创建、查询、更新。
package user2. 函数注释（函数上方）
说明函数功能、参数、返回值。
// GetAge 根据用户ID获取年龄信息
// 参数：id - 用户唯一标识
// 返回：用户年龄，错误信息
func GetAge(id int) (int, error) {
return 18, nil
}3. 结构体/接口注释
// User 用户信息结构体
type User struct {
Name string // 用户名
Age int // 年龄
}四、完整规范 Demo（可直接运行）
main.go 全覆盖注释规范，无语法错误👇
// Package main 程序入口包，用于演示Go注释规范
package main
import "fmt"
// UserInfo 用户信息结构体
// 包含用户基础信息
type UserInfo struct {
UID int // 用户ID
Name string // 用户名称
}
// GetUserInfo 获取用户信息函数
// 参数：uid - 用户唯一ID
// 返回：UserInfo - 用户信息结构体
func GetUserInfo(uid int) UserInfo {
// 返回固定测试数据（单行注释：演示返回逻辑）
return UserInfo{
UID: uid,
Name: "Go学习者",
}
}
/*
main 函数
程序主入口，执行演示逻辑
多行注释：用于大段说明
*/
func main() {
// 获取用户信息
user := GetUserInfo(1001)
// 打印结果
fmt.Println("用户信息：", user)
}运行命令：
go run main.go五、注释最佳实践（必看）
✅ 必须写注释的地方
- 1. 包声明：每个包写用途
- 2. 导出函数/结构体（大写开头）：必须写文档注释
- 3. 复杂逻辑：说明思路
- 4. 常量/枚举：说明含义
❌ 不要写的注释
- 1. 废话注释：
i++ // i 自增 - 2. 注释与代码不一致
- 3. 超长无意义注释
- 4. 注释代替清晰命名
六、godoc 文档生成（专业技能）
1. 启动本地文档
godoc -http=:6060打开浏览器：http://localhost:6060
即可看到自动生成的规范文档。
七、注释规范速查表
| 位置 | 注释类型 | 示例 |
|---|---|---|
| 包顶部 | 多行/单行 | // Package xxx 说明 |
| 导出函数 | 单行 | // 函数说明 |
| 结构体 | 单行 | // 结构体说明 |
| 字段 | 行尾注释 | Name string // 用户名 |
| 内部逻辑 | 单行注释 | // 逻辑说明 |
八、新手避坑指南
- 1. 多行注释不能嵌套
/* 外层 /* 内层 */ 错误 */ - 2. 导出函数（大写）必须写注释，否则 IDE 警告
- 3. 注释要简洁清晰，不啰嗦
- 4. 保持注释与代码同步更新
📌 总结
- 1. 单行注释：
//用于行内、简短说明 - 2. 多行注释：
/* */用于包、大段说明 - 3. godoc 规范：包、函数、结构体必须写文档注释
- 4. 最佳实践：简洁、准确、有用、不废话
写好注释，让代码自带说明书，专业度直接拉满✨
#Go语言 #Go注释 #Go规范 #godoc #编程入门
