Unnarrate
與 unslop 搭配使用。Unslop 修正 AI 散文的語氣;這個工具則刪除根本不該存在的文字:後設評論 —— 那些向受眾敘述成品本身的文字。進度條已經宣告進度;旁邊再寫「執行時顯示進度」是第二個冗餘的符號。代理程式之所以不斷產生這類文字,是因為它們把思考鏈敘述到觸及的每一個表面。
刪除測試
刪除任何僅包含以下內容的句子、標籤或註解:
- 對所在成品的描述(「本節說明…」),
- 讀者已經能看到的內容(重述標籤的工具提示、重述下一行程式碼的註解),或
- 產出過程(
// 應要求提取為輔助程式)。
兩個判斷標準決定模糊案例:
- 在心裡刪除它。 如果讀者毫無損失,它就是無操作 —— 看似做了什麼但實際上沒改變任何事的文字。
- 可移植性。 如果這行文字可以原封不動地出現在另一個專案、另一個 PR 或不同程式碼上方,它就沒有說明這個專案的任何獨特性。刪除它。
按表面類型決定刪除內容
UI 文案
- 描述介面已自行執行行為的文案:「安裝時顯示進度」、「載入時出現轉圈圈」、「清單會自動更新」。控制項本身就是符號;不要添加語言符號。
- 在可見轉圈圈旁邊的「載入中…」文字;「檔案上傳成功」→「檔案已上傳」。
- 重述標籤的工具提示和說明文字:欄位「出生城市」,提示「請輸入您的出生城市」。
- 位置敘述:「點擊下方按鈕提交」、「從下拉選單選擇選項」。
- 入門/引導標記文案:列舉每個控制項,而非指向那個非顯而易見的操作。
- 無障礙重複:
<button>上的aria-label="提交按鈕",alt="圖表圖片"(螢幕閱讀器已宣佈角色)。
文件和 README
- 「本文件說明…」、「在本指南中,我們將…」、「歡迎閱讀 X 的文件」。直接開始內容。
- 只宣告後續章節的概述章節;結尾的「總而言之」段落重述頁面內容。
- 重述簽章的 Docstring(
get_user(id)— 「根據 id 取得使用者」);<summary>取得或設定 X</summary>。PEP 257 明確禁止這種寫法。 - 範例程式碼上方的「以下範例示範如何…」;重述相鄰程式碼區塊的散文。
- 對任何專案都成立的功能清單和章節介紹。
程式碼註解
- 重述下一行程式碼:
// 匯入 React、// 回傳值、// 遍歷項目。 - 章節橫幅:
// ===== 輔助程式 =====、// --- 步驟 3:驗證 ---。 - 計劃和階段敘述:
// 階段 2:重構、// 使用新建立的 Foo 模型。 - 變更日誌敘述:
// 從 useState 改為 useReducer、// 移除了舊的處理程式。Git 歷史已記錄這些。 - 針對審查者而非未來讀者的註解:
// 注意:我保留了這個行為不變。
提交和 PR
- 逐檔案重述 diff 的清單;「此 PR 新增…」後面緊跟著標題原文。
- 以重述內容填滿的範本區段:「測試計劃:執行測試」但沒有具體細節。
- 努力敘述:「全面重構」、「謹慎保留向後相容性」。陳述審查者可以驗證的事實。
保留 —— 並非所有敘述都是無操作
- 即時敘述是符號;靜態敘述是警訊。 代理在運作時串流顯示「正在安裝相依套件…」是真實的回饋。而描述這個回饋存在的文案則是反模式。
- 「為什麼」的註解保留: 理由、不變量、關於非顯而易見行為的警告、問題和事件的連結。規則刪除的是重述,而非所有註解 —— 與周圍程式碼的註解密度保持一致。
- 包含表面無法顯示資訊的指示保留: 格式(「YYYY-MM-DD」)、限制(「8 個以上字元」)、副作用(「這會電子郵件通知團隊」)、不可逆警告。
- 真正的替代文字保留。 刪除「圖片的…」前綴,保留圖片所呈現內容的描述。
- 附帶追蹤連結的待辦事項保留; 單純的
// TODO:改進這部分則刪除。
應用方式
- 掃描受影響的表面,找出上述模式。刪除,不要改寫 —— 大多數命中案例不需要任何替代。
- 當刪除造成真正的空缺時,改進成品本身(更清晰的標籤、不言自明的控制項),而不是改進敘述。
- 然後對殘留的文字執行 unslop。
reference/terminology.md 按社群命名此現象(後設論述、空洞對話、顯而易見的註解、無操作)並提供來源,便於引用或擴展檢查清單。