Go注释是接口契约的一部分，导出标识符需用完整Doc注释说明功能、参数、返回值和约束，首行以被注释项名开头；结构体字段应具体描述含义与限制，内部逻辑用行注释解释“为什么”；注释须与代码同步，避免冗余，协同测试与日志提升可维护性。

Go 语言的注释不是装饰，而是接口契约的一部分。写好注释的关键在于：让调用者不看源码也能理解“它做什么、怎么用、有什么限制”。Go 的注释规范简单但有分量，尤其在导出（首字母大写）的标识符上，注释直接影响 godoc 生成的文档质量。

导出函数/方法必须写完整 Doc 注释

以大写字母开头的函数、方法、结构体、字段、常量等，若希望被其他包使用，必须用 块注释（/**/）且紧贴声明上方，首行是简洁的功能描述，后续可说明参数、返回值、行为约束和示例。

• 第一行必须是完整的句子，以被注释项名称开头，如："Add returns the sum of a and b."
• 参数用 Args: 引导，每行一个；返回值用 Returns:；错误情况用 Panics: 或 Errors:（若返回 error）
• 避免空行隔开——Doc 注释必须连续，否则 godoc 会截断

✅ 正确示例：

// Add returns the sum of a and b.
// Args:
//   a: first integer operand
//   b: second integer operand
// Returns:
//   the arithmetic sum
func Add(a, b int) int {
    return a + b
}

内部实现用行注释（//）讲清“为什么”，而非“是什么”

非导出标识符（小写字母开头）不需要完整 Doc 注释，但关键逻辑处应使用 // 行注释解释意图、权衡或边界条件。重点不是重复代码，而是补充上下文。

• 比如：// use atomic.StoreUint64 instead of direct assignment to ensure visibility across goroutines
• 避免无意义注释：// i++ → i increases by one（代码已自解释）
• 算法关键步、并发安全假设、性能敏感点，值得加注

结构体字段注释要具体，尤其影响序列化或 API 的字段

导出结构体的每个导出字段都应有简短注释，说明其含义和业务约束（如是否允许为空、取值范围、格式要求）。这对 JSON/XML 序列化、API 文档、数据库映射非常关键。

• ✅ 好注释：// Name is the user's full name, required, max 100 chars
• ✅ 含 tag 提示：// Email is the primary contact address. Required. json:"email" validate:"required,email"
• ❌ 模糊注释：// user email

注释不是替代测试和日志，而是协同增强可维护性

好的注释不会承诺未实现的行为，也不会掩盖设计缺陷。它和单元测试、结构化日志一起构成可维护性的三角支撑：

• 测试验证“它是否按注释说的做”
• 日志记录“它在运行时实际做了什么”
• 注释定义“它本应如何被理解和使用”

当发现注释与代码行为不一致时，优先修正代码——注释滞后是技术债的典型信号。

基本上就这些。Go 的注释语法本身极简（只有 // 和 /* */），真正的难度在于持续保持注释与代码同步、聚焦使用者视角、拒绝冗余。写注释不是填任务，是写轻量级契约。