OpenFlare/.agents/skills/go-style-core/references/FORMATTING.md

格式化参考

gofmt 是必须的

所有 Go 源文件 必须 符合 gofmt 的输出。没有例外。

# 格式化一个文件
gofmt -w myfile.go

# 格式化目录下所有文件
gofmt -w .

其他格式化工具：

工具	用途
gofmt	标准格式化工具（必须使用）
goimports	gofmt + import 管理
gofumpt	gofmt 的更严格超集

---

括号

Go 比 C 和 Java 需要更少的括号。控制结构（if、for、switch）的语法中不需要括号。运算符优先级层次更短更清晰，所以 x<<8 + y<<16 的含义就如空格所暗示的那样 — 不像其他语言。

---

MixedCaps（驼峰命名）

Go 使用 MixedCaps 或 mixedCaps，从不使用下划线：

// 好
MaxLength    // 导出常量
maxLength    // 非导出常量
userID       // 变量

// 不好
MAX_LENGTH   // 不使用 snake_case
max_length   // 不使用下划线

例外：

• 测试函数名可以使用下划线：TestFoo_Bar
• 与 OS/cgo 交互的生成代码

---

行长度

Go 中 没有严格的行长度限制，但避免过长的行。Uber 建议软限制为 99 个字符。

指导原则：

• 如果一行感觉太长，重构 而非仅仅换行
• 不要在缩进变化之前换行（函数声明、条件语句）
• 不要将长字符串（URL）拆分成多行
• 换行时，将所有参数放在各自的行上
• 如果已经尽可能短了，就让它保持长行

按语义换行，而非按长度：

不要仅仅为了保持短行而添加换行符，当长行更具可读性时（例如，重复性的行）。因为你所写的内容而换行，而非因为行长度。

长行通常与长名称相关。如果你发现行太长，考虑名称是否可以更短。去掉长名称往往比换行更有帮助。

这个建议同样适用于函数长度 — 没有"函数永远不超过 N 行"的规则，但确实存在太长的情况。解决方案是改变函数的边界在哪里，而非计算行数。

// 不好：随意的行中断
func (s *Store) GetUser(ctx context.Context,
    id string) (*User, error) {

// 好：所有参数各占一行
func (s *Store) GetUser(
    ctx context.Context,
    id string,
) (*User, error) {

---

局部一致性

当风格指南未做规定时，与附近代码保持一致：

有效的 局部选择：

• 错误格式化使用 %s 还是 %v
• 带缓冲 channel 还是 mutex

无效的 局部覆盖：

• 行长度限制
• 基于断言的测试库