正文裡的對象要用它是什麼來命名,序數、計數與字母代號是作者腦中的索引
正文裡每一個被反覆提到的對象都需要一個名字,而那個名字的職責跟程式裡的變數名稱相同:讀者只看到這個名字,就知道它指的是什麼。「語意模型」「選寫法」「當場報錯」「日期差自連接」做得到這件事;「第一支」「第三步」「第一級」「A1」做不到——它們是作者替一份清單編的索引,要讀者手上也有那份清單才解得開。
這一類名字在程式碼審查裡過不了關。沒有人會接受 branch1、step3、level1、a1 當變數名稱,理由是讀到呼叫點的人得跳回定義處才知道它是什麼,跟風格無關。教材裡同一個名字出現幾十次,每一次都是一個呼叫點。
失效的形態
一次 SQL 教材分類的全面檢視裡,這一類名字有三種形態,而三種常常出現在同一句裡。
計數當成集合的名字。 「三支」「七步」「兩個軸」「七個決定」。數字是成員數,不是這群成員共同的性質,所以讀者從「三支」得不到任何一支在講什麼。它同時是 #156 的形態——成員數一變名字就失真——而這裡的損害先於失真:成員數沒變的時候它已經讀不懂。
序數當成成員的名字。 「第一支」「第三步」「第五節」「第一級」「前提一」。序數只說這個成員排在第幾個,而讀者需要的是它是什麼。這個形態在作者用它推導的時候最嚴重。一個分類的目錄頁寫過這樣一句:
第一支的篇落在七步的第三、四、六步,第二支落在第五、七步,第三支落在第七步。
這句話是兩份索引的對照表,裡面沒有任何一個詞指向內容。讀者要同時持有「三支各是什麼」與「七步各是什麼」兩張清單才解得開,而作者寫它的時候兩張清單都在腦中,所以讀起來精確。改成用內容命名之後是:
講語意模型的篇用在選寫法、補前提、對邊界這幾個決定上,講文字之外的決定者的篇用在量代價與交付上。
字母代號當成實體的名字。 一張表把五個寫法標成 A 到 E,之後正文寫「A 與 B 從寬鬆的那一家搬到嚴格的那一家時屬於這一級」「D 與 E 在這裡」;另一篇把四種查詢形態標成 A1、A2、B、C,之後寫「A1 與 A2 的差別只在條件的形狀」「C 的排名從最後一名跳到第一名」。每一個字母都要讀者回到表格對一次。那五個寫法各自有現成的描述——未分組欄位、WHERE 用別名、同表未取別名、字串比對、空值排序——字母省下的只是幾個字。
這一類名字從哪裡來
它們是作者整理結構時的工作語言。規劃一個分類的時候,作者把篇章分成幾組、把流程切成幾步,而在規劃階段用編號稱呼它們是合理的:成員還在變,內容名還沒定,編號是最便宜的把手。問題在工作語言沒有在交稿前換掉,而且它跟另一個缺陷一起出現——作者把自己的編排思路寫進了正文。「本分類其餘各篇各自處理其中一步的機制,而讀者逐篇讀過去的時候看不出它們是同一條路上的七站」「兩個軸的用法不同:想理解這個語言為什麼長這樣,照三支讀」,這些句子在描述作者怎麼組織這個分類,而描述組織的時候最順手的詞就是組織用的編號。所以看到序數名字密集的段落,也要一併問這一段是不是在講作者的編排、而不是講主題。
為什麼既有的審查掃不到
作者與同源的 reviewer 都持有那張清單。寫的人剛定義完「三支」,讀的 reviewer 讀過整份規劃,兩者讀到「第一支」都能當場解開,所以這個名字在他們的閱讀裡沒有成本。成本只落在從搜尋或路由進來、落在中段的讀者身上,而審查的人不在那個位置。
既有的規則管到了這一類,而觸發條件放在另一個時間點。#155 的〈類別序數〉一節已經要求把「第二類」「第五步」換成類別名,它的論證是集合變動時序數會漂移——補了一類,九處「第三類」同時指錯。那個論證要等集合變動才成立,而這個分類的「三支」「七步」從寫成到檢視都沒有變過,於是每一輪審查都可以合理地判定它不漂移、放行。本卡的損害不需要等:集合沒變的時候,每一次出現都要讀者回頭查一次。#156 管的是標題裡嵌進成員數,同樣以成員增減為失效條件。字母代號(「A1」「D 與 E」)則兩張都沒有涵蓋,它不在任何標題裡,也不是類別序數。字句層 keyword bank 的「位置與集合指涉」列了「前者/後者/前兩篇」,列不到「第一支/第三步/第一級」,因為它是從論述文歸納的,而這一類的詞綴隨內容變(支、步、級、節、層、階段、前提、種)。
判讀方式
變數名稱測試:把這個名字當成程式裡的變數名稱,它過不過得了程式碼審查。step3 過不了,chooseQueryForm 過得了。
落點測試:讀者從搜尋落在這一句,沒讀過前文,他知不知道這個名字指什麼。要翻回去查才知道的,就是作者的索引。
掃描的入口是詞形,而詞綴要按內容換:
1rg -n "[一二三四五六七八九十兩]支|[一二三四五六七八九十]步|第[一二三四五六七八九十][步支節級層章階種類條項]|前提[一二三四五]|兩個軸|另一個軸|這個軸" content/<分類>
2rg -n "\b[A-E][0-9]?\b 那|\b[A-E][0-9]? 與 [A-E][0-9]?\b" content/<分類>命中是候選。三種情形合規:緊鄰清單、隨即逐一具名展開的計數(「下面四個追問」後面立刻列出四個);量測事實裡的數字(「差三個量級」「七十倍」);外部凍結的編號(RFC 段號、法條、題號)。一段文字裡序數確實是順序本身的時候——「寫在最前面的 SELECT 在語意上排在倒數第二步」,前一句剛列完那串步驟——它描述的是位置,不是在當名字用。
修法
用它是什麼來命名。 分組用它回答的問題(「語意模型」「文字之外的決定者」),流程的步驟用動作(「追問需求」「選寫法」「量代價」),分級用它的判斷標準(「當場報錯」「等資料才報錯」「靜默而輸出不同」「靜默且輸出相同」),並排的做法用描述(「日期差自連接」「等值自連接」)。名字長一點沒關係——它要讓讀者不必翻回去,而那個成本乘上它出現的次數。
段標的序號拿掉,引用改成節名或內容。 「第五節那張表」改成「代價量測那張表」。段標保留序號時,作者會持續用序號引用它,所以拿掉序號是讓這個習慣沒有把手。
標題與網址裡的計數一起改。 「這條路有七步」這種標題把計數當成全篇的主題詞,網址 the-seven-steps 也是。改名時用 Hugo 的 aliases 保留舊網址,站內連結全部改到新網址。
跟著刪掉編排思路。 描述「各篇怎麼分組」「兩篇怎麼分工」「改哪一篇」的句子是作者的維護資訊,不是讀者要的內容。讀者需要的只有範圍交代,而範圍交代要帶內容名(「列數那一半在〈連接產出的是新的關係〉那一篇」)。
論述基礎與限制
證據來自一個 SQL 教材分類的一次檢視:目錄頁有十七處序數或計數名字,一篇總覽文章十一處,一篇實例文章八處,加上兩篇文章的字母代號共五十五處。一個分類的一次觀測只證明這一類名字會在全面檢視後殘留、而且會集中在規劃結構的那幾頁,不證明它在每個分類的密度都這麼高。掃描指令的詞綴也是從這一個分類歸納的,換到別的分類要先盤點那裡用的是哪些詞綴。
跟其他抽象層原則的關係
- #155 引用章節用語意標題、不用位置編號——那一張的〈類別序數〉一節要求同一件事,而它的失效條件是集合變動;本卡把失效條件移到集合不變的當下,所以「這個集合不會再變」不構成放行的理由。兩者的修法相同:序數換成類別名。
- #156 集合命名用角色、不內嵌數量——那一張的損害是成員數變了名字失真,本卡的計數形態在成員數不變時就已經讀不懂;兩張合起來看,計數當名字在兩個時間點都有成本。
- #270 敘事的解碼材料要在讀者已讀的文本裡——序數與代號是「作者的地圖」最純粹的形態:解碼它需要的正是那張地圖本身。
- #364 摘要另一份內容時寫出成員,計數只告訴讀者清單有多長——同一個成因的另一個位置:本卡是計數或序數當成一個對象的名字,#364 是計數當成一段摘要的全部內容;計數式摘要沒有被當成名字,所以本卡的掃描放過它。
- #84 Naming 是 iterated artifact——規劃階段的編號是第一版命名,本卡是那一條在教材上的具體出口:交稿前第一版的工作語言要換成內容名。
- #367 切開一個集合之前先寫切分的依據,再替每一塊命名——本卡管已有名字而名字是索引的對象;那一張管還沒被命名、只以「一部分」「另一半」出現的對象,並補上先寫切分依據這一步。
Case
2026-09-24,SQL 教材分類。使用者先指出總覽文章開頭一段「這七個決定⋯⋯讀者逐篇讀過去的時候看不出它們是同一條路上的七站」是作者的寫作脈絡,不該寫進文章;接著指出同一篇「三支與七步的對應」「同一步」「另一個軸」這些名字是最糟的寫法,因為它們在程式碼裡絕不會被接受。那一篇與它的實例文章在寫成當天走過三輪多輪審查,第二輪含理解探針,而這一類名字沒有被任何一輪回報。改寫的範圍擴到整個分類:三個分組改用各自的問題命名,步驟改用動作名,引擎差異的四個分級改用判斷標準命名,兩篇的字母代號換成描述,總覽文章的標題與網址一併改名。同一天稍後的逐段審查又在〈合不合法由引擎驗〉找到「第一種/第二種/第三種錯法」被單獨引用十餘次,這一篇在上述改寫裡被漏掉,原因是掃描指令的詞綴清單沒有「種」——補上之後正對照命中。這一條示範了本卡「詞綴要按內容盤點」那句限制的實際代價。