这是一个面向 Kotlin / Jetpack Compose 代码库的工程实践技能，主题是如何让“带有合法例外的设计规则”长期可维护。原文以“语义表面不使用硬编码白色”为示例规则：悬浮在照片或视频之上的控件合理地保持白色，因此该规则可执行但并不绝对，而这种“可执行但非绝对”的规则最容易腐化——几个月后没人分得清剩下的硬编码颜色哪些是有意为之。
【用途】 提供一套低成本、机械化的做法：在规则建立处声明规则；在破坏规则处写一行理由；保留一条能同时列出合规与例外位置的命令。
【主要做法】
- 在规则建立处一次性声明规则，例如设置主题化子树的文件 KDoc；两份规则会像其他重复代码一样漂移。
- 理由写在调用点上一行，而非文件头部说明；头部说明在新增代码后即失真，且审阅时不在视线内。
- 谨慎使用块注释：一组并列兄弟节点可共用一条注释，但一旦被移动或复制，理由就不再随行，看起来与违例无异；若某组可能被拆分，应逐个标注。
- 不要标注合规行，否则审计中例外将无法找到。
- 审计范围按结构派生（例如读取主题角色的文件），并说明该列表含义；全包扫描会因大量未受规则约束的代码而永远失败，最终没人运行。
- 区分“例外”与“范围外”：未主题化表面上的颜色不属于例外。
- 预期审计会查出未注释命中，并逐条注释或修复；引用他人打印的数字无意义。
- 基于注释窗口的启发式会高估合规率（附近无关注释也会被计为合规），因此一旦例外率足够低，应把规则固化为 lint 或静态分析检查；注释约定只作为工具无法判断的规则（如“是否绘制在视频之上”）的兜底。
【使用方式】 原文给出可复制的命令。检查规则声明是否可检索： grep -rn --include='.kt' --exclude-dir=build "no hardcoded whites|hardcoded white" . 运行审计（文件列表由推导得出，需按自身规则的范围与 token 修改两处 grep）： D=$(dirname "$(grep -rl --include='.kt' --exclude-dir=build '^class .ContentState(' .)") grep -rl "MaterialTheme.colorScheme" $(find "$D" -name '.kt') | while read -r f; do awk -v F="$(basename "$f")" '/Color.(White|Black)/ { print (p1 ~ //// || p2 ~ //// ? " ok " : "BARE ") F ":" NR } { p2=p1; p1=$0 }' "$f" done 统计计数（随时间观察的指标）： D=$(dirname "$(grep -rl --include='*.kt' --exclude-dir=build '^class .ContentState(' .)") grep -rl "MaterialTheme.colorScheme" $(find "$D" -name '.kt') | while read -r f; do awk '/Color.(White|Black)/ { print (p1 ~ //// || p2 ~ //// ? "ok" : "BARE") } { p2=p1; p1=$0 }' "$f" done | sort | uniq -c 并抽查三条 ok 命中；若其中有附近注释与颜色无关，说明启发式误报，真实已注释数低于统计值。
【适用场景】 已有主题化设计体系、存在硬编码颜色需定期审计的 Kotlin 代码库，以及任何“可执行但允许例外”的编码约定治理。
【限制】 原文未提供安装命令、收费、平台或具体工具集成信息；注释窗口启发式会误报，统计值偏高；块注释在代码移动后失效。