代码注释门禁
io.github.PostHog/posthog/writing-code-comments
判定一条代码注释是否该存在,并强制留下的注释解释“为什么”而非“是什么”。在用任何语言(Python、TypeScript、Go、Rust、SQL)编写或编辑注释前务必使用,也用于评审新增注释的 diff。清除 clutter 代码库的注释类型:复述代码的旁白、变更历史与聊天上下文备注(“之前做了 X”“按 PR #123”“AI:”)、易失效的度量与现状标记(“约 20 分钟构建”“目前”“今天”)、被注释掉的代码与冗余 docstring。保留有价值的注释:不显然的 why、关于非本地影响的警告、指向未来读者无法自行重建上下文的线索。不适用于面向用户的文案(见 `/writing-user-facing-copy`)或提交信息。