去叙述
与 unslop 搭配使用。Unslop 修复 AI 文本的语调;这个工具删除那些根本不应该存在的文本:元评论——即叙述产物本身以面向其受众的写作。进度条本身就已经在宣告进度;旁边写着“运行时会显示进度”是第二个多余的指示符。AI 智能体持续产生这类文本,因为它们将其思维链叙述到它们触碰的每一个表面上。
删除测试
删除任何唯一内容属于以下情况的句子、标签或注释:
- 对所在产物的描述(“本节描述……”),
- 读者已经可以看到的内容(重复标签的工具提示,重复下一行的注释),或
- 生成它的过程(
// 根据要求,提取到辅助函数中)。
两个检查决定模棱两可的情况:
- 在脑海中删除它。 如果读者没有损失任何东西,那它就是一个无操作——一段看似有作用但实际上不改变任何东西的文本。
- 可移植性。 如果该行可以原封不动地出现在另一个项目、另一个 PR 或不同的代码上方,那么它就没有说明本项目的任何信息。删掉它。
按表面需要删除的内容
UI 文案
- 描述界面已自行执行的行为的文案:“安装时会显示进度”、“加载时会显示旋转指示器”、“列表会自动更新”。控件本身就是指示符;不要添加语言的指示符。
- 可见旋转指示器旁边的“正在加载……”文本;“文件上传成功” → “文件已上传”。
- 重复标签的工具提示和帮助文本:字段“出生城市”,提示“输入您的出生城市”。
- 位置叙述:“点击下方按钮提交”、“从下拉菜单中选择一个选项”。
- 新手引导/教练标记文案,列举每一个控件,而不是指向非显而易见的一个操作。
- 可访问性冗余:
<button>上的aria-label="提交按钮",alt="图表图片"(屏幕阅读器已宣布角色)。
文档和 README
- “本文档描述……”、“在本指南中,我们将……”、“欢迎阅读 X 的文档”。直接从内容开始。
- 仅用于宣布后续章节的概述部分;末尾重复页面内容的“总结”段落。
- 重复函数签名的文档字符串(
get_user(id)— “通过 id 获取用户”);<summary>获取或设置 X</summary>。PEP 257 明确禁止了这一点。 - 示例上方的“以下示例展示了如何……”;重复相邻代码块的散文。
- 对任何项目都成立的功能要点和章节介绍。
代码注释
- 重复下一行:
// 导入 React,// 返回值,// 遍历项目。 - 章节横幅:
// ===== 辅助函数 =====,// --- 步骤 3:验证 ---。 - 计划和阶段叙述:
// 阶段 2:重构,// 使用新创建的 Foo 模型。 - 变更日志叙述:
// 从 useState 改为 useReducer,// 移除了旧的处理程序。Git 历史记录了这些。 - 面向审阅者而非未来读者的注释:
// 注意:我保留了此行为不变。
提交信息和 PR
- 逐文件重复 diff 的要点列表;“此 PR 添加了……”,后面跟的是标题原样。
- 填充了重复内容的模板章节;“测试计划:运行了测试”,没有具体细节。
- 努力叙述:“全面重构”、“仔细保留了向后兼容性”。陈述审阅者可以验证的事实。
保留——并非所有叙述都是无操作
- 实时叙述是指示符;静态叙述是问题信号。 智能体在运行时流式输出“正在安装依赖……”是真实的反馈。而描述该反馈存在的文案才是反模式。
- 保留“为什么”注释: 基本原理、不变性、关于非显而易见的警告、指向问题和事件的链接。规则删除的是重复,而不是注释——与周围代码的注释密度匹配。
- 保留包含界面无法显示的信息的指令: 格式(“YYYY-MM-DD”)、约束(“8+ 个字符”)、副作用(“这将给团队发送邮件”)、不可逆性警告。
- 保留真正的替代文本。 删除“……的图片”前缀,保留图片内容的描述。
- 保留带有跟踪链接的 TODO; 仅
// TODO:改进此项则删除。
应用方法
- 扫描变更过的表面,查找上述模式。删除,不要重写——大多数命中点不需要替换。
- 当删除留下真正的空白时,修复产物(更清晰的标签、不言自明的控件),而不是修复叙述。
- 然后对保留下来的内容运行
unslop。
reference/terminology.md 按社区命名了该现象(元话语、快乐谈话、显而易见的注释、无操作),并给出了来源,供引用或扩展检查清单使用。