“样式”规则可能改变程序语义和公开 API
原文依据:3 处该 Skill 不只调整格式:它要求集合永不为 nil、建议把超过四个参数改成 options struct,并要求积极取消导出。nil 与空集合可能具有不同的协议含义;修改签名或导出状态会改变调用方可用的 API。
应用于现有项目时,可能改变 JSON 输出、破坏依赖 nil 的逻辑,或导致下游代码无法编译。取消导出还可能成为破坏性 API 变更。
这不只是排版建议。若在现有代码上机械应用,“集合永不为 nil”可能改变 JSON 或调用方用来区分 nil 与空集合的语义;把参数改为 options struct 会改变函数签名;取消导出会让包外调用无法编译。风险只在这些规则被用于修改现有 API 时出现。用户可要求仅报告问题,不改集合语义、公开符号或函数签名,除非逐项批准。
Slices and maps MUST be initialized explicitly, never nil. Nil maps panic on write; nil slices serialize to `null` in JSON (vs `[]` for empty slices), surprising API consumers.查看另外 2 个位置
- Functions SHOULD be **short and focused** — one function, one job.- Functions SHOULD have **≤4 parameters**. Beyond that, use an options struct (see `samber/cc-skills-golang@golang-design-patterns` skill).- **Parameter order**: `context.Context` first, then inputs, then output destinations.- Naked returns help in very short functions (1-3 lines) where return values are obvious, but become confusing when readers must scroll to find what's returned — name returns explicitly in longer functions.- **Dot imports** pollute the namespace and make it impossible to tell where a name comes from — never use in library code- **Unexport aggressively** — you can always export later; unexporting is a breaking change. → See `samber/cc-skills-golang@golang-gopls` skill to unexport safely — its rename updates every call site atomically and refuses the change when lowercasing a method would break interface satisfaction, a breakage grep/sed silently ships.