概念位置

SRP 是 SOLID 五原則的第一條。Martin 在《Agile Software Development: Principles, Patterns, and Practices》（2002）把它寫成「一個類別應該只有一個改變的理由」；2014 年他在〈The Single Responsibility Principle〉一文說明「理由」指的是人，並把原則改寫成兩句方向相反的指示：

Gather together the things that change for the same reasons. Separate those things that change for different reasons.

前一句要求把因同一個理由改變的程式碼放在一起，後一句要求把因不同理由改變的程式碼分開。切分的人只執行後一句，會把同一個理由的程式碼拆散到很多檔案，於是那群人每次提出變更，修改的人都要同時改好幾處，這就是 Shotgun Surgery；只執行前一句的極端是把所有程式碼都放在一起，於是不同理由的變更擠在同一個模組，這就是 Divergent Change。SRP 要求兩句同時滿足：因同一個理由改變的程式碼在同一個模組，因不同理由改變的程式碼在不同模組。在《Clean Architecture》（2017）裡，Martin 把定義收斂成「A module should be responsible to one, and only one, actor」，actor 指的是要求同一類變更的一群人。

理由的計數單位是改動的種類，提出的人用來辨認種類。 一個 actor 要求的是同一類改動，所以理由可以從兩邊辨認：從提出變更的人，或從他們要求的改動種類。兩邊對得上時（財務部門要求的都是薪資規則的改動）看哪一邊結果都一樣；對不上時以改動種類為準——同一個人轉達好幾個職能的需求時，他提出的改動屬於不同理由；不同的人提出同一類改動時，仍是同一個理由。

Martin 在 2014 年那篇文章裡說明這條原則的源頭是 David Parnas 1972 年的論文〈On the Criteria To Be Used in Decomposing Systems into Modules〉與 Edsger Dijkstra 提出的 separation of concerns：模組的切法要依「什麼會一起變」決定，不依程式執行的步驟決定。他在《Agile Software Development》的單一職責那一章也寫明，這條原則就是 Tom DeMarco 與 Meilir Page-Jones 所說的 Cohesion（內聚），只是把判斷依據從功能上的相關換成讓模組改變的力量。

「只做一件事」是另一條原則。 SRP 最常見的誤讀是「一個類別只做一件事」。Martin 在《Clean Architecture》第七章說確實有一條原則是這樣講的，那條原則的對象是函式：一個函式只做一件事，用在把大函式拆小的重構裡。那一條管的是函式內部的步驟，判斷依據是程式碼在做什麼；SRP 管的是模組的邊界，判斷依據是誰會要求它改變。兩條原則的單位與依據都不同，所以一個只做一件事的類別仍然可能有兩個改變的理由，一個做了好幾件事的類別也可能只有一個。

可觀察訊號與例子

Martin 的例子是一個 Employee 類別，裡面有三個方法：calculatePay 依財務部門的規則計算薪資，reportHours 依營運部門的需要產生工時報表，save 依技術團隊選定的方式寫進資料庫。三個方法服務三群人——財務長、營運長、技術長各自管轄的部門——所以這個類別有三個改變的理由。三個方法放在同一個類別，損害出現在它們共用程式碼的時候：Martin 在《Clean Architecture》裡舉的是 calculatePay 與 reportHours 共用一個計算正常工時的 regularHours 方法：財務部門要求調整加班時數的算法，負責這次修改的工程師改了那段共用計算，營運部門的工時報表跟著變，而營運部門沒有提出任何變更。

判斷一個模組有幾個理由，要看它的變更要求的是哪幾種改動、各由哪一個職能決定，不看它有幾個方法：

• 修改紀錄裡有好幾個不相干的需求改同一個檔案（不相干指要求的改動屬於不同種類）：這是改變理由不只一個的間接量測。不同理由的修改由不同的人同時進行時，改動落在同一處就會合併衝突，沒有文字衝突時也要重跑測試確認沒有改壞對方；Martin 把合併列為違反單一職責的另一個症狀。用 git 歷史統計每個檔案被幾個不同的需求修改，再逐個 commit 歸類，做法在從修改紀錄畫模組邊界，造成等待的幾種情形在那一篇的〈修改競爭與單一職責原則〉。
• 一個需求的修改改壞了另一個需求在乎的行為：上面 Employee 的情形。兩個需求互不相干，卻因為住在同一個模組而互相影響。
• bug 修正與重構不另算一個理由。Martin 的說法是 bug 修正與重構是程式設計師的責任，不是程式的；歸類時，一個 bug 修正併進它所修的那段程式碼原本屬於的那一類。
• 所有需求都由同一個人提出時（例如所有票都由同一位 PM 開），看提出的人分不出理由，要看每個需求要求的是哪一種改動。以一個擋下跨工作目錄 commit 的守衛腳本為例：解析 git 命令語法的改動跟著 git 的寫法變，判斷其他代理人是否正在工作的改動跟著團隊的並行流程變，擋下時印給使用者的訊息措辭跟著使用者回饋變，這三種改動各是一個理由。

依改動種類計數理由的判斷也適用於文件：一份文件被好幾個不相干的主題修改，就有好幾個改變它的理由，做法在依職責拆分文字文件。

設計責任

套用 SRP 的設計責任是讓每一群提出變更的人，各自只需要改一個地方，而且改的時候不會動到別人在乎的行為。執行的判斷問句是：列出一段時間內改過這個模組的需求（範圍要涵蓋幾輪需求，選法見從修改紀錄畫模組邊界〈用 git 歷史量出熱點〉的「統計的時間範圍」一條），逐一寫出要求的是哪一種改動、由哪一個職能決定；改動種類有兩種以上，就有兩個以上的理由，可以考慮依理由切開。

依技術層次切（驗證器、資料存取、寄信服務各一個類別）常常與依理由切重合，因為驗證規則、資料庫結構與信件內容通常由不同的人決定；兩種切法分岔時，以每個類別會被哪一個職能要求改變為準。切開之後反過來檢查：同一個理由的變更是否需要同時改好幾個新模組，是的話就切過頭了，要把那幾個新模組併回來。

SRP 與 開放封閉原則常一起使用：SRP 決定模組的邊界畫在哪裡，開放封閉原則決定模組裡哪些部分對外公開、讓其他模組不必修改它就能擴充，哪些留在內部。開放封閉原則在 Python 的寫法與例子在開放封閉原則。

保留原本的匯入路徑、改寫分派、避免循環匯入這幾件事的寫法依語言而定，Python 的做法在拆分 Python 模組；Go 搬移時用 type alias 保留舊的匯入路徑、一次只搬一個邊界，在 7.5 以 domain 重新整理 package，多檔案、多個 package 與 import cycle 的基礎在 1.5 從單檔到多檔案；規則文件、操作手冊這類文字文件的拆分寫在依職責拆分文字文件。

修改競爭與單一職責原則

修改競爭指的是處理不相干需求的人或代理人要改同一個檔案。兩個需求不相干，指它們要求的改動屬於不同種類（例如一個改命令的解析方式、一個改提示訊息的措辭）；讀修改紀錄的人要逐個 commit 歸類之後才判得出來，下文〈從修改紀錄找出職責邊界〉說明做法。git 只在兩邊改動的行重疊或相鄰時產生合併衝突，所以同一個檔案的修改不一定互相阻擋；會讓它們互相等待的是三種情形：

• 改動落在同一處：例如兩個需求都在同一份清單或檔尾追加一筆。處理第一個需求的人先改、先合併，處理第二個需求的人拉最新版、解衝突、重跑測試。
• 合併沒有文字衝突，而行為互相影響：兩個需求各改一個函式，git 合併成功，而後合併的那一方 rebase 之後仍要重跑測試，確認兩邊沒有改壞對方。
• 並行的代理人共用同一個工作目錄：兩方的改動還沒提交就混在同一份檔案裡，而 commit 記錄的是整份檔案的內容，任一方提交都會帶走另一方的改動，所以一方要等另一方提交或清空改動才能動手。

團隊排好修改的順序、加強溝通，能縮短每次等待的時間，而一個檔案承載的職責越多，落在它身上的不相干修改越多，等待的次數跟著增加。只有一個人依序開發時沒有等待成本，不相干的修改落在同一個檔案仍然有代價：一個需求的改動有機會改壞另一個需求在乎的行為。讓一個需求的改動碰不到另一個需求在乎的行為，這種隔離正是單一職責原則要保護的對象。

單一職責原則（SRP）把職責定義成改變的理由：一個模組應該只有一個改變的理由，而理由的計數單位是改動的種類。提出變更的那群人（需求的提出者，例如某個業務部門）通常各自要求同一類改動，所以可以拿來辨認種類；同一群人要求了好幾類改動、或不同的人要求同一類改動時，照改動的種類算（定義、Martin 的原文與「只做一件事」為什麼是另一條原則，在那張卡片）。這個定義把抽象的「職責」換成了可以觀察的對象——改變的理由。版本歷史記下了每一次改變，也記下了它是為了哪一個需求（票、issue、PR）而做，需求數因此可以當成改變理由的間接量測（proxy measure）。

本篇說的模組是有對外介面的程式單位（Coupling（耦合）卡片有同樣的界定），量測的單位則是檔案。Python 一個檔案就是一個模組，Dart 不用 part 時一個檔案就是一個 library，兩者等價；Go 的一個 package 由好幾個檔案組成，熱點檔依職責拆成同一個 package 裡的幾個檔案，不同需求改的就是不同檔案，git 層面的修改競爭就解掉了；拆出的這幾類是否需要各自的對外介面、是否再拆成不同的 package，是另一個判斷。

腳本數的是不同的需求，不判斷這些需求相不相干，所以需求數只是篩選訊號：讀排行的人用它決定要回頭讀哪幾個檔案的修改紀錄，一個檔案實際有幾種改變的理由，要等他逐個 commit 歸類之後才判定。讀排行的人只從前段挑檔案，排在後段的檔案不會再被逐個 commit 檢查，所以會讓需求數少算的情形（見〈用 git 歷史量出熱點〉的「一張票涵蓋好幾類改動」）要另外留意。本篇範例 commit 守衛的需求都服務同一件事（擋下跨工作目錄的 commit），而它們要求的改動分成三種：命令語法跟著 git 的寫法變、並行政策跟著團隊的工作流程變、提示措辭跟著使用者的回饋變，三種改動的起因不同、發生的時間也不同，即使所有票都由同一位 PM 開，只看開票者是誰分不出來，看每張票要求的改動種類才分得出來。這正是 Divergent Change（發散式變更）：一個模組因為不同的理由、以不同的方式被修改。

行數與不同需求數的量測對象

團隊判斷一個檔案要不要拆時，常用的門檻是行數，例如超過 300 行就考慮拆。行數是檔案過大的症狀，而它在兩種檔案上給出的結果與不同需求數相反：

行數量的是檔案的大小，不同需求數量的是一個檔案可能混了幾種改變的理由，SRP 在意的是改變的理由有幾種。開發者照行數把 900 行的解析器切成三份、不看修改落在哪裡時，同一主題之後的修改常常要同時改好幾個檔；一個需求改多個檔案是 Shotgun Surgery（散彈式修改）。與它成對的發散式變更，正是本篇用修改紀錄量的那種壞味道（從程式碼結構偵測的規則在 Code Smell 檢查清單的〈B1. Divergent Change〉一節），發散式變更在並行開發時造成的等待，就是修改競爭的成本。

用 git 歷史量出熱點

量測的前提是需求與檔案的對應查得到。本篇從 commit 標題裡的需求編號取（commit 訊息帶票號的慣例見 Commit message vs source code doc 的〈Bug 號、ticket 連結、incident 紀錄〉一節；那裡的例子把票號寫在內文，下面的腳本只讀標題，處理方式見〈只讀 commit 標題〉那一條）。想避開只讀標題這個限制的團隊，也可以從 issue tracker 取：匯出每個 PR 連到的 issue 與 PR 改的檔案，整理成「檔案 → 需求編號集合」的對應，就是腳本裡 collect_changes 回傳的那個形狀，之後的排行與判讀照用，而且沒有只讀標題帶來的限制。

commit 標題帶有需求編號（票號、issue 號）時，下面的腳本算出每個檔案被幾個不同需求改過。下文把排行前段、與同一次統計裡的其他檔案相比被明顯更多不同需求修改的檔案稱為修改熱點（簡稱熱點），例如排行前幾名與其後的檔案之間有一段明顯的落差；它不設絕對的門檻，也沒有固定的名次。它與效能分析裡「最常執行的程式路徑」那種熱點是兩件事；git 歷史分析的文獻裡也有 hotspot（Adam Tornhill 在《Your Code as a Crime Scene》裡結合修改頻率與程式碼的複雜度），本篇數的是不同需求數，不數 commit 次數，也不乘複雜度。腳本以 Python 寫成，只呼叫 git log、不讀程式碼，放進 Go 或 Dart 的 repo 照樣能跑。

 1"""依 commit 標題中的需求編號，統計每個檔案被幾個不同需求修改。"""
 2import collections
 3import fnmatch
 4import os
 5import re
 6import subprocess
 7
 8ISSUE_ID = re.compile(r"#(\d+)")  # 依專案的 commit 慣例調整
 9PR_SUFFIX = re.compile(r"\s*\(#\d+\)\s*$")  # squash merge 在標題結尾附加的 (#PR號)
10STRIP_PR_SUFFIX = True  # 只在用 squash merge、標題結尾的 (#N) 是 PR 號時設 True
11# 工具產生的檔案，不列入統計；樣式比對檔名或相對 repo 根目錄的路徑，依專案的套件管理與程式碼產生工具調整
12# generated/* 只比對根目錄那一層，子目錄裡的要另外寫 */generated/*
13EXCLUDE = {"*.lock", "package-lock.json", "go.sum", "*.g.dart", "*.pb.go", "*_pb2.py",
14           "generated/*", "*/generated/*"}
15EXCLUDE_ISSUES: set[str] = set()  # 橫切的需求編號（相依套件升級、全域改名），不列入統計
16
17def excluded(path: str) -> bool:
18    return any(fnmatch.fnmatch(path, p) or fnmatch.fnmatch(os.path.basename(path), p) for p in EXCLUDE)
19
20def collect_changes(since: str, path: str = ".") -> tuple[dict[str, set[str]], int]:
21    log = subprocess.run(
22        # core.quotePath=false：非 ASCII 檔名照原樣輸出，不轉成跳脫碼
23        ["git", "-c", "core.quotePath=false", "log", f"--since={since}", "--no-merges",
24         "--name-only", "--format=@@%s", "--", path],
25        capture_output=True, text=True, check=True,
26    ).stdout
27
28    issues_per_file: dict[str, set[str]] = collections.defaultdict(set)
29    current: set[str] = set()
30    skipped = 0
31    for line in log.splitlines():
32        if line.startswith("@@"):
33            subject = line[2:]
34            if subject.startswith('Revert "'):
35                current = set()  # revert 的標題帶著被還原那個 commit 的 PR 號
36                continue
37            if STRIP_PR_SUFFIX:
38                subject = PR_SUFFIX.sub("", subject)
39            current = set(ISSUE_ID.findall(subject)) - EXCLUDE_ISSUES
40            skipped += not current
41            continue
42        if line and current and not excluded(line):
43            for issue in current:
44                issues_per_file[line].add(issue)
45    return issues_per_file, skipped
46
47def report(since: str, top: int = 20) -> None:
48    changes, skipped = collect_changes(since)
49    ranked = sorted(changes.items(), key=lambda kv: -len(kv[1]))
50    for path, issues in ranked[:top]:
51        print(f"{len(issues):3d} 個需求  {path}  {' '.join(sorted(issues))}")
52    print(f"略過 {skipped} 個標題沒有需求編號的 commit")
53
54if __name__ == "__main__":
55    report("2 weeks ago")

1# 存成 hotspots.py 之後，在 repo 的根目錄執行（Python 3.9 以上）
2python3 hotspots.py

腳本裡影響計數的設計：

• 統計的時間範圍：report() 的引數是 git log --since 接受的時間字串（"2 weeks ago"、"2026-01-01"）。執行腳本的人設定的範圍要涵蓋幾輪需求，讀排行時才看得出同一個檔案被不同需求反覆修改；範例的兩週適合需求密集的專案，修改頻率低的專案要拉長。一個檔案被幾個需求修改才算多，這個數字跟著時間範圍變，所以讀排行的人比較的是檔案在排行裡的相對位置，不比絕對數字。

• 統計的目錄：collect_changes 的 path 預設是 "."，指的是執行腳本時所在的目錄；執行腳本的人從子目錄執行時，腳本只統計那個子目錄底下的檔案。repo 裡文件與程式碼混在一起、執行腳本的人只想統計其中幾個目錄時，在 git log 的 -- 之後列多個路徑。

• 只讀 commit 標題：腳本傳給 git log 的 --format=@@%s 讓 git 對每個 commit 只輸出標題。把需求編號寫在內文或 trailer（訊息結尾 Refs: #160 這種 鍵: 值 形式的欄位）的專案，腳本會靜默略過這些 commit；這類專案改用 %B 取完整訊息時，內文的行會和檔名混在一起，分隔方式與解析都要跟著改。

• PR 號：GitHub 的 issue 與 PR 共用同一組 #N 編號，squash merge（把整個 PR 壓成一個 commit 合併）又會在標題結尾附上 (#PR號)，只改 ISSUE_ID 分不開兩者；STRIP_PR_SUFFIX 為 True 時，腳本先去掉標題結尾的 (#N) 再比對。STRIP_PR_SUFFIX 這個設定只適用用 squash merge 的 repo，而且需求編號要寫在 PR 標題裡；習慣在標題結尾寫 (#45) 引用 issue 的專案，要把 STRIP_PR_SUFFIX 設成 False，否則那個 issue 號會被刪掉。需求編號與 PR 編號格式不同的專案（例如需求用 PROJ-123），改 ISSUE_ID 就分得開。revert 的標題會把被還原那個 commit 的 PR 號帶進引號裡，腳本略過 Revert " 開頭的標題（不計入最後印出的略過數）。

• 工具產生的檔案：lock 檔、每個 PR 都跟著升號的版號檔、產生的程式碼，每個需求都會改到，排行會被它們佔滿，而它們沒有任何人帶著意圖去編輯；執行腳本的人在統計前把檔名或檔名樣式（*.g.dart、*/generated/*）加進 EXCLUDE；路徑樣式比對的是相對 repo 根目錄的完整路徑。

• 改名與橫切的需求：git log 加了 --name-only 不追蹤改名，大量重新命名之後，舊路徑與新路徑各自計數。相依套件升級、全域改名、格式化這類橫切的需求會讓大量檔案各加一，排行前段一整批同時出現的檔案，多半來自同一個橫切需求；EXCLUDE_ISSUES 用來排除這類需求的編號。

• 沒有編號的 commit：腳本最後印出略過的 commit 數。Dependabot、Renovate、發版機器人這類 bot 的 commit 也不帶需求編號，讀排行的人判讀前先扣掉它們（git log --format 加 %an 看作者）。扣掉之後的數字仍接近全部 commit（例如九成以上），統計沒有意義；commit 完全不帶編號時排行是空的、只印出這一行。這時讀排行的人改用〈從修改紀錄找出職責邊界〉的做法，讀 commit 標題與 git show 人工歸類；沒有排行可以挑檔案時，先數每個檔案被幾個 commit 改過，取前段當候選：

  1# 時間範圍用與熱點統計相同的範圍
  2git log --no-merges --since="2 weeks ago" --name-only --format= | LC_ALL=C sort | LC_ALL=C uniq -c | sort -rn | head -20

  這條指令數的是每個檔案被幾個 commit 改過：同一個需求分成多次 commit 時每次各算一次，大檔案又常在開發者處理別的需求時被順手修改，所以一個檔案排在前段，不代表它的改變理由比較多。讀排行的人只拿這份清單挑出要讀修改紀錄的檔案，每個檔案有幾種改變的理由，要等逐個 commit 歸類之後才判定。

• 編號是不是需求：略過數量的是多少 commit 沒有編號，量不出比對到的 #N 是不是需求——標題裡的 #N 也可能是文件編號、討論串引用或內部卡片的序號。執行腳本的人跑完之後，抽幾筆被計入的 commit 讀標題，確認編號指的是需求，再看排行。

• --no-merges：git log 預設不列出 merge commit 改了哪些檔案，所以 merge 不影響排行；標題沒有編號的 merge（Merge branch 'x'）會被算進略過的 commit 數，腳本加的 --no-merges 讓 git 不輸出它們。改用 -m 時，merge 對每個 parent 各列一次檔案：對第一個 parent 列出的是分支帶進來的檔案，它們除了分支 commit 的編號，又記到 merge 標題的編號下；對第二個 parent 列出的是主線同期改過的檔案，它們被記到一個沒改過它們的需求名下。改用 --first-parent 時只走主線，分支上的 commit 不列出，改動改由 merge commit 列出、記在 merge 標題的編號下；--first-parent 與 --no-merges 一起用時，以 merge commit 合併的 repo 會失去全部分支上的改動。

• 一張票涵蓋好幾類改動：一張概括性的票（一張「維護」票、一個 epic 編號）底下做了好幾類改動時，有好幾個理由的檔案只算一個需求，排不進前段。這一類少算的方向腳本看不出來，常用這類票的專案要把它們拆回實際的需求，或把那些票號另外列出來，對它們改過的檔案直接做逐個 commit 歸類。

• 一則 commit 帶多個編號：腳本用 ISSUE_ID.findall 取出標題裡的全部編號。一個 commit 同時處理多個需求時，它改過的每個檔都會記到每個需求名下。排行裡一整批檔案同分、而它們共有的編號都來自同一個 commit 時，讀排行的人要排除的是那個 commit，不是那幾個編號（排除編號會連帶扣掉其他檔案正當的計數）：修改腳本的人把 --format 改成 @@%h %s，subject = line[2:] 之後先切出開頭的 hash，讀到要排除的 hash 時清空 current，其餘照原本比對標題。

• 把子需求歸到同一個主題：點號格式的子需求（例如 #120.3），正規式 #(\d+) 只比對到第一段數字，本來就會算進根需求 120。子需求若有獨立編號（例如父需求 #120、子需求 #135），執行統計的人要另備一份父子對照表，把子需求歸到根需求再計數；不歸併的話，同一主題的連續修改會被誤算成多個改變理由。〈熱點的分類與處理方式〉表格裡「同一主題的連續演進」那一列，指的是子票已經歸到根需求之後的計數。

• 同一功能的各輪追修另開新編號：同一個功能經過好幾輪審查時，每一輪的追修常另開一個新需求，編號不同、彼此沒有父子關係，父子對照表也歸併不了。這些編號在排行裡各算一個，一個被反覆修改的功能看起來像好幾個需求在搶改同一個檔，這個檔因此排進前段，讀排行的人逐個 commit 歸類時，時間會先花在它身上。讀排行的人對排在前段的檔案，先用〈從修改紀錄找出職責邊界〉那條 git log --format='%h %s' 列出 commit 標題，把屬於同一功能的編號合併成一個主題，再用合併後的主題數與其他檔案比較；合併之後仍排在前段，才進入逐個 commit 歸類。腳本不讀標題的語意，哪些編號屬於同一功能要由人判讀。

熱點的分類與處理方式

排行前段的檔案有些該拆、有些不該拆，讀排行的人先依下表認出每個檔案的熱點類型，再照該列處理：

讀排行的人對照這張表時，有些檔案同時符合兩種類型，例如 i18n 字串檔：來源語系的字串由開發者在每加一個功能時登記一筆，屬於集中登記檔；翻譯語系的字串由翻譯平台寫入，屬於工具產生的檔案。兩種類型的處置不同，所以他依每次修改的寫入者是人還是工具，把這個檔案的修改分到兩種類型，各自照該列處理。

熱點統計以檔案為單位計數，所以不落在單一檔案上的競爭不會出現在排行裡。例如 schema 遷移：開發者每次改資料庫結構都新增一個遷移檔，兩個分支同時各加一個遷移時，合併後會出現兩個都排在最後的遷移，競爭發生在遷移的先後順序上，而每個遷移檔在統計裡都只被一個需求改過。

lock 檔與產生的程式碼由工具改寫：開發者執行套件管理或程式碼產生工具時，工具依套件清單或來源定義重新寫出整個檔，內容由工具的輸入決定，所以這些修改歸不進任何一種職責：執行腳本的人在統計前把它們加進 EXCLUDE 排除；兩個分支同時改到同一個 lock 檔而衝突時，解衝突的人重新執行產生它的工具，不逐行挑選兩邊的內容。每個 PR 都升號的版號檔，團隊改由發版時打的 tag 衍生版號之後，PR 就不必再改它。

版號寫在開發者手動編輯的檔案裡時（package.json 的 version、__init__.py 的 __version__），同一個檔也有人為了需求修改其他內容，把整個檔加進 EXCLUDE 會連這些修改一起從統計拿掉；逐個 commit 歸類的人略過只改版號的那幾個 commit。根本的解法同樣是改由 tag 衍生版號，開發者就不必再手動修改這個欄位。

集中登記檔的處置跟一般程式碼相反。註冊表的職責是集中列出所有項目，每加一個功能就要登記一次，所以修改它的需求數會隨功能數一起增加。開發者把它依職責拆成三份註冊表之後，每次登記仍然要改其中一份，衝突只是換到另一個檔案；兩個需求都在同一份清單的尾端追加，照樣是相鄰的改動。這類檔案的解法是讓每次登記不碰同一個檔案：每個項目一個片段檔，由載入端掃描目錄合併。這要載入端由自己控制；設定檔由外部工具讀取、而工具只認單一檔案時，片段檔進版控，由一個產生步驟（例如建置前執行的一支合併腳本）合併成那一個檔，合併出來的檔案當成工具產生的檔案從統計排除。

登記的對象是程式碼時，由誰掃描依語言而定：Python 在執行期匯入目錄底下的每個模組（寫法見拆分 Python 模組的〈把巨型分支改成自動登記的分派表〉），Go 在同一個 package 裡讓每個檔案用自己的 init() 登記，不需要掃描；既沒有執行期掃描、也沒有這類機制的語言，走上面那個產生步驟。

片段檔的代價是登記關係不再寫在一個看得到的地方，放進目錄的半成品檔也會被登記。登記項目之間有先後的語意時（路由表先比對到的先生效、middleware 依序執行、依類型分支裡子類別要排在父類別之前），掃描目錄得到的是檔名或檔案系統列出的順序，改成片段檔可能悄悄改掉哪個項目先被比對到；每個片段要宣告自己的排序鍵，由載入端依它排序，特徵測試要涵蓋會被兩個項目同時比對到的輸入。

集中本身有用途時（例如公開 API 的介面檔，集中是為了讓每次新增都經過同一處審查），或衝突多半是單行、由工具重新產生就能解決時（例如套件清單檔），保留集中、接受衝突也是一個出口。

測試檔的修改跟著它測的產品檔走，所以只有測試檔是熱點時，讀排行的人回到它測的產品檔判讀。產品檔也是熱點，測試隨產品檔一起拆。產品檔不是熱點，多半代表這個測試檔一次測了好幾個產品模組；產品檔已經拆成幾個模組、測試卻還集中在一個檔，也是同一種情形，兩者都依它測的模組拆成對應的測試檔。另一種情形是這個測試檔是共用的 fixture 或測試案例清單，每個需求都在裡面登記一筆，那是集中登記檔，依上一段處理。

從修改紀錄找出職責邊界

職責的邊界記在修改紀錄裡：每個需求改的是哪一種職責，讀它的 commit 就知道。熱點統計腳本的 report() 在每個檔案後面印出了改過它的需求編號，負責歸類的人要看每個需求做了什麼時，列出這個檔案的 commit 標題：

1# 時間範圍用與熱點統計相同的範圍，路徑換成要拆的那個檔案
2git log --no-merges --since="2 weeks ago" --format='%h %s' -- guard.py

把每個需求歸到它改的職責（並行期間指多個代理人同時在各自的工作目錄開發的期間）：

1需求 A：修正命令解析遇到引號時的錯誤        → 命令解析
2需求 B：新增「並行期間」的判斷條件           → 狀態判斷
3需求 C：提示訊息改成指引使用者改寫命令       → 訊息產生
4需求 D：解析器支援 -C 參數                   → 命令解析
5需求 E：並行期間改依工作位置過濾             → 狀態判斷

逐個 commit 歸類的人看的單位是每個 commit 改到的程式：git show <hash> 看得到那個 commit 改了哪些函式。類別依需求要求的改動種類建立，與歸類的先後順序無關。長期計畫（橫跨多張票、為同一個目標分批進行的工作，例如分好幾輪做完的一次重構）有根需求編號時照根需求歸併；沒有的話，它的 commit 改到好幾處，也只歸進其他需求已經要求過的那些種類，計畫本身不構成一個模組。只有一個需求、改到同一個檔案的好幾處，是同一主題的連續演進，不產生新的類別；那個需求若要同時改好幾個檔案，是散彈式修改的訊號，處理見 Shotgun Surgery 卡片。bug 修正與重構不另算一個理由，依它修的那段程式碼原本屬於哪一類歸進那一類。一段程式（例如兩類都呼叫的計算函式）被兩類需求各自改過時，記成兩類的共用處，不歸給先改它的那一類，拆分時再判斷它跟著哪一類走。這個例子裡每個需求只改到一類，所以逐個需求列出來就是逐個 commit 的結果。

多數需求（需求數超過一半；這是判斷用的經驗值，不是量測結果）都同時改到某兩類時，這兩類對需求而言是同一個改變的理由，歸類的人把它們歸成同一類——依它們切開，每個需求都要同時改兩個新檔，就是散彈式修改。需求本來就是跨層的功能切片時（例如每個新參數都要同時加解析規則與擋下訊息），另外看有沒有需求只改了其中一類：一個都沒有，才把兩類併成一類。

歸類之後，每一類職責是一個候選模組，這個例子分出命令解析、狀態判斷與訊息產生。歸類後只剩一類時，這些需求要求的是同一類改動，這個檔案只有一個改變的理由（內聚），或者它是集中登記檔，歸類的人回到〈熱點的分類與處理方式〉的表重新判斷。歸出的幾類裡有一類是「登記一筆」（同一個檔裡同時有處理邏輯與一張對照表）時，先把那張表拆成自己的檔，依集中登記檔處理，其餘幾類照候選模組判斷。

團隊決定候選模組是否拆開時，看這些修改的代價有沒有出現：有沒有人在這個檔案上等待、有沒有一個需求改壞了另一類在乎的行為，出現任一種就有拆的理由。各類在統計範圍裡只被改過一兩次、而且時間上一個接一個、沒有兩個需求同時在改時，代價還沒有出現，記下這次的歸類，下次重跑統計時再判斷。

拆分時與語言無關的做法：特徵測試、搬移與修改分開提交、單向依賴

團隊決定切法之後，動手拆分的人要把 guard.py 依這三類拆成 command_parse.py、state.py、messages.py，同時維持對外行為不變。做到這一點有三件事與語言無關，各語言的寫法放在各語言模組；要拆的邏輯在其他檔案另有副本時，還有一件事排在這三件之前。

拆分前先收斂散在多個檔案的重複實作。 同一段邏輯在好幾個檔案各寫了一份時（例如讀取同一份設定的函式，在共用模組與幾支腳本裡各有一份），拆分的人先把它收斂成一份、其他檔案改為呼叫它，收斂合併之後再拆各個熱點檔。不先收斂有兩個代價：各份副本跟著需求各自被修改，同一個修正常常只落在其中一份，其餘幾份留著舊的行為；這段邏輯每改一次都要同時改好幾個檔（散彈式修改），這幾個檔都被推進熱點排行，各自拆完之後，每個新模組裡仍帶著一份副本，修改照樣要同時改好幾個新檔。所以收斂是這幾個拆分共同的前置：它自成一個需求、先合併，之後各熱點檔再以收斂後的版本為基準拆分，拆出的模組依賴那一份共用實作。收斂只把同一份知識合成一份；各份已經分歧時，先判斷是某一份漏修，還是兩類需求本來就要不同的行為，後者照 DRY 卡片的判斷各留一份。前者在收斂時會改到漏修那幾份的行為，這個行為改動與合併副本分開提交，理由見下文〈搬移與修改分開提交〉。

拆分前用特徵測試鎖住行為。 拆分前後跑同一組測試、結果相同，才證明拆分沒有改到對外行為。這種測試叫特徵測試（characterization test）：預期值取自拆分前程式當下的實際輸出，不是規格上應該如何。既有的測試已經涵蓋要鎖住的輸入與輸出時，直接用它們；沒有時才補特徵測試，拆完、正確性測試覆蓋同一段行為之後，照那張卡片〈設計責任〉的說明移除它。它抓得到拆分在測到的輸入與斷言的輸出上造成的任何差異，包括原本就存在的錯誤被「順手修好」；沒有斷言的輸出抓不到。測試表要涵蓋應該被擋下或應該回報錯誤的反例：只驗證正常情況會放行的測試表，在拆分改壞了擋下的判斷時依然全綠。

搬移與修改分開提交。 搬移和修改混在同一個 commit 裡，測試一紅，就分不出是搬錯了還是改錯了，所以純搬移的 commit 不同時修改行為，行為的修改放在之後的 commit。git diff --color-moved 會把搬移過的行與新寫的行用不同顏色標出，用來確認一個 commit 裡只有搬移。拆分要把原檔換到新路徑時（例如 Python 改成同名套件），改名也單獨提交一個只改名的 commit：git 依內容相似度判定改名，改名與大量搬移混在同一個 commit 時，留下來的那份檔案只剩原檔的一小部分，git 認不出它是改名而來，git log --follow 就追不到改名之前的歷史。只改名的 commit 保住的是留下原名的那一份；其他新檔是新建的，--follow 追不到它們的內容在拆分前的修改，日後想看搬走的程式之前怎麼改的人，用 git blame -C -C <新檔>：-C 給兩次時，git 也會在建立這個檔的 commit 裡找從其他檔複製過來的行，標出它們在原檔的來源 commit。

拆出來的模組依賴只朝一個方向。 依賴單向時，改動下層的模組可能影響上層，改動上層不會影響下層，一次修改會波及哪些模組可以預測；兩個模組互相依賴時，改任何一邊都可能波及另一邊。判斷上下層的依據是誰需要知道誰：被較多拆出模組使用、而且自己不需要知道其他拆出模組的那一個在下層，兩個條件都要成立。這個例子裡 command_parse.py 只把指令字串解析成結構，在最下層；state.py 與 messages.py 使用解析結果；組合三者的那一層在最上面。兩個新模組互相呼叫時，拆分的人看它們過去的修改：幾乎每次都一起發生，代表它們是同一類職責、歸類時切錯了，併回同一個模組（判斷見 Coupling 卡片的〈設計責任〉）；修改各自發生，先確認兩個方向的呼叫是否都必要，有時拿掉其中一邊就夠了；兩邊都必要，多半代表中間有一塊共用的定義沒有抽出來，例如兩邊都用到的資料型別，把它往下抽一層，讓兩者都依賴它。往下抽的前提是那塊定義只因一個理由改變；兩類需求各自會改它時（Martin 的 regularHours 例子，見單一職責原則卡片），抽成共用正是那張卡片警告的情形，各留一份（判斷同一份知識與碰巧長得一樣，見 DRY 卡片）。熱點檔拆成同一個 package 裡的幾個檔案時（Go 的常見做法），編譯器不檢查同一個 package 裡檔案之間的依賴方向，這一條作用在之後是否再拆成不同 package 的判斷上。

拆分的時機與等待中的需求

拆分合併的時間點，決定等待中的需求以哪一版為基準。拆分先合併，等待中的需求以新版本為基準，各自只改自己職責所在的新檔：

1拆分前：命令解析、狀態判斷、訊息產生各有一個需求在等，三個都要改 guard.py → 一個接一個
2拆分後：處理命令解析需求的人改 command_parse.py，狀態判斷的改 state.py，訊息產生的改 messages.py → 可以同時進行

原本要一個接一個做的三個需求，拆分之後可以平行處理。拆分若在某個需求開工之後才合併，那個需求的分支改的是舊的 guard.py，rebase 到拆分之後的版本時，git 的改名偵測（內容相似度預設 50% 以上就判定為改名，下文的「過半」就是指這個相似度）決定衝突的形態。原檔留在原路徑、只剩組合三者的那一層時（Go 常把 guard.go 留著當組合層），沒有改名，衝突以一般的內容衝突出現在原檔，處置同下；原檔被換到新路徑或刪除時，有兩種形態：

• 沒有一份新檔保留原檔過半的內容：git 判定 guard.py 被刪除，出現 modify/delete 衝突。
• 有一份新檔保留了原檔過半的內容：git 把它當成 guard.py 改名而來，衝突以一般的內容衝突出現在那份新檔，衝突區塊裡是已經搬到其他模組的舊函式。解衝突的人照一般衝突處理接受這一段，會把搬走的函式重新塞回那份新檔，分支的改動落在那份新檔裡的舊函式副本上。工具是否擋下這份副本，依語言與檔案配置而定：Go 把幾類拆成同一個 package 裡的檔案、Dart 用 part 把一個 library 拆成好幾個檔時，重複宣告在編譯時就被擋下；Python 這類每個檔案各自是一個命名空間的語言不報錯（Dart 不用 part 時也是，編譯與 dart analyze 都不擋），又分兩種情形——那份新檔沒有匯入同名函式時，副本沒有人呼叫，分支的改動等於消失；那份新檔先匯入了同名函式（例如 from .command_parse import parse_command）、塞回的 def 排在 import 之後時，副本蓋掉匯入的名字，被呼叫的反而是帶著分支改動的副本，而真正的新家留著舊版。後一種情形 ruff 或 flake8 的 F811 規則（pyflakes 的 redefinition of unused 檢查）抓得到。

兩種形態的處置相同：解衝突的人把這個分支的改動移到那一職責所在的新檔，不接受衝突區塊裡整段的舊程式碼。rebase 沒有衝突時，分支的負責人也要檢查一次：分支在被當成改名目標的那份新檔裡新增的函式會乾淨合併，即使它屬於另一類職責。用 git diff main --stat 與 git diff main 看分支新增的每個函式落在哪個檔（main 換成拆分合併進去的那條分支）。在檔案各自是命名空間的語言裡，拆分前就有的測試在上面這幾種情形下（modify/delete、內容衝突，以及 Python 的兩種副本）仍然全綠；分支為自己的改動補的測試可能紅，也可能因為副本蓋掉了匯入的名字而全綠，所以上面那個 git diff 的檢查不論落在哪一種情形都有效。這也是拆分要排在等待中的需求開工之前合併的原因。

長期分支很多、團隊找不到「沒有需求在進行中」的時間點時，有三種退路：先把進行中的分支合完再拆，排一個短暫的凍結窗口；一次只抽出一類，原檔保留其餘內容，衝突只落在動過那一類的分支、位置也預測得到；rebase 之後跑會抓重複定義的工具（Go 的編譯、TypeScript 的 tsc、Python 的 ruff F811），再加上面那個 git diff 檢查。分支都很短的團隊（例如 trunk-based development）少有這個情形。

拆分之後重跑熱點統計：驗證切法與新檔再成熱點的判讀

團隊用拆分之後的修改紀錄驗證拆分是否切對。驗證的對象是拆分之後的修改，所以過了幾輪需求之後重跑熱點統計，report() 的引數設成拆分合併的那一天；拆分本身的需求編號加進 EXCLUDE_ISSUES，否則拆分那個 commit 會讓每個新檔各多算一個需求。重跑統計的人比較拆出來的各個新檔被幾個需求修改，並看每個需求是否只改了一個新檔：多數需求同時改到兩個新檔，代表當初把同一個改變的理由切成了兩類。

某個新檔很快又成為熱點時，讀排行的人把它的修改再歸類一次：

• 修改落在拆分時已有的幾類而混在一起：當初的職責分類切錯了位置。
• 出現拆分時沒有的一類：多了一種新的職責。
• 每次修改都是登記一筆：那個新檔本身是集中登記檔。
• 修改全部落在它自己那一類：在這一類裡照〈從修改紀錄找出職責邊界〉再歸類一次。依需求要求的改動種類再分一次：這些需求要求的改動屬於兩種以上的種類（例如有的改解析規則、有的改輸出格式），代表這一類粒度太粗，可以再拆；全部屬於同一種，代表這一類就是程式最常變動的那一處，拆分已經把變動集中在那裡，不必再拆。

拆分時若另抽了一個讓幾個新檔共用的定義模組（例如幾個模組都用到的資料型別），它被每個需求都改到時，常見的原因是共用定義抽得太大，裡面混了只有某一個模組用的型別，開發者把那些型別搬回使用它的模組。

這次驗證之後，團隊照原本的時間範圍定期重跑熱點統計：讀排行的人從〈熱點的分類與處理方式〉重新判讀新出現在排行前段的檔案。

拆分的語言實作：拆分 Python 模組（同名套件與重新匯出、monkeypatch 的替換目標、自動登記的分派表、拆出模組之間的循環匯入）、7.5 以 domain 重新整理 package（type alias 過渡、每次只搬一個邊界、測試保護搬移）、1.5 從單檔到多檔案（Go 的多檔案、多 package 與 import cycle）。文字文件的對應做法：依職責拆分文字文件。

與其他教材的分工

路由方向是單向的：本模組的定義不依賴任何語言的實作；語言模組引用本模組的卡片建立概念。

章節與卡片

• 從修改紀錄畫模組邊界：用 git 歷史量出被多個不同需求修改的檔案、分類熱點、逐個 commit 把需求歸到職責、拆分時與語言無關的做法（特徵測試、搬移與修改分開提交、單向依賴）、拆分合併的時機與拆完之後的驗證。範例是一支 Python 寫成的 commit 守衛，量測與歸類不依賴語言；語言的寫法在各語言模組（目前有 Python，Go 的拆分基礎在 1.5 從單檔到多檔案）。
• Knowledge Cards：單一職責、開放封閉、DRY、內聚、耦合與兩種對應的壞味道。

Backlog

範圍決定

2026-10-19 評估過把 DDD、UX Design、Testing 移進本模組，三者都維持獨立、與本模組並列：

• DDD：理解的對象是領域模型，自有詞彙與案例庫；它引用本模組的單一職責與開放封閉原則，關係是引用而不是隸屬。
• UX Design：理解的對象是使用者與畫面，與程式碼結構沒有交集。
• Testing：理解的對象是驗證怎麼分層，涵蓋可觀測性、UI 自動化與 agent 產出程式碼的驗證，大半與程式碼結構無關。

本模組的內容改由抽取補齊：語言模組裡講語言無關原則的段落，把定義與判斷標準抽成本模組的卡，語言寫法留在原處並連過來。DDD 的 Dependency Injection 與 Test Seam 卡評估後留在 DDD：兩張的引用全部在 DDD 內部，內容以 port、adapter、composition root 定義，搬出會切斷那組卡的互連。

重新評估的條件：DDD 的章節開始處理與領域模型無關的模組設計，或讀者路線固定成先讀本模組再讀 DDD 的一條階梯。

概念位置

Divergent Change 與 Shotgun Surgery 描述的是同一組對應關係的兩種失衡：改變的理由與模組之間應該一對一。同一個理由的好幾個需求都改同一個模組是正常的內聚；屬於不同理由的需求改同一個模組是 Divergent Change，同一個理由的一個需求要改好幾個模組是 Shotgun Surgery。單一職責原則的兩句指示各自對應一種：「把因不同理由改變的程式碼分開」修的是 Divergent Change，「把因同一個理由改變的程式碼放在一起」修的是 Shotgun Surgery。

可觀察訊號與例子

Fowler 給的辨識方式是：修改某個模組時，心裡想的是「加一種資料庫要改這三個函式，加一種金融商品要改那四個函式」——兩種變更各自集中在模組裡的幾個函式，卻共用同一個模組。可以觀察到的訊號有三種：

• 修改紀錄：同一個檔案在一段時間內被好幾個不相干的需求修改。以需求編號統計每個檔案被幾個不同需求改過，再逐個 commit 歸類，做法在從修改紀錄畫模組邊界。
• 並行開發的等待：處理不相干需求的人反覆在同一個檔案上解合併衝突、或等對方合併之後重跑測試。
• 檔案內的分群：模組裡的函式可以分成幾群，每一群只被某一類需求修改，群與群之間很少一起改。

站內偵測規則（以方法分組數判斷）與 Extract Class 的操作範例在 Code Smell 檢查清單。

設計責任

修正 Divergent Change 的方向是依改變的理由把模組切開：先找出每一類需求各自會改的那一群函式與資料，再用 Extract Class（拆出類別）或把模組改成套件、每一群移到一個子模組。切開之前先用測試鎖住現有行為，切開之後確認同一類需求的變更只需要改一個新模組；若同一類需求要同時改好幾個新模組，代表切過頭，產生了 Shotgun Surgery。

概念位置

單一職責原則有兩句方向相反的指示：把因不同理由改變的程式碼分開，把因同一個理由改變的程式碼放在一起。只照前一句切，最常出現的結果就是 Shotgun Surgery——切的人看到「做了好幾件事」就切開，沒有檢查那幾件事是不是總是一起改。它與 Divergent Change 都是改變的理由與模組沒有一對一對應的情形，修正方向相反，所以拆檔之後要兩個方向都檢查。

可觀察訊號與例子

Fowler 指出這種壞味道的主要風險是漏改：變更散在很多地方時，很難全部找到，漏掉一處就留下不一致。常見的形態有三種：

• 依行數拆檔：把一個 900 行、只屬於同一個需求連續演進的解析器切成三份，切的時候不看修改落在哪裡，之後同一個主題的修改常常要同時改好幾個檔。行數判斷與不同需求數的判斷在這種檔案上給出相反的結論，對照在從修改紀錄畫模組邊界的〈行數與不同需求數的量測對象〉。
• 新增一個欄位要改每一層：欄位定義、資料存取、序列化、畫面各在一個檔案，加一個欄位就要依序改過每一層。這種情形有時是分層架構刻意付的成本，判斷時看這幾層是不是總是一起改、而且由同一個理由驅動。
• 同一段規則複製在好幾處：規則改了，每一份複本都要找出來改。這與 DRY 處理的是同一件事，Python 的寫法在DRY 原則。

站內偵測規則與修正範例（Extract Interface、Introduce Facade）在 Code Smell 檢查清單。

設計責任

修正 Shotgun Surgery 的方向是提高內聚，把總是一起改的函式與資料收回同一個模組：用 Move Function、Move Field 把散落的函式與資料移到一處，散開的那幾個模組若只剩空殼就用 Inline Class 併回去。判斷問句是：最近幾次同一類變更，各改了哪幾個檔案；每次都改同一組檔案，那一組就是應該合併的候選。合併之後回頭檢查另一個方向：新的模組是否因此開始被不相干的需求修改，是的話就併過頭了，變成 Divergent Change。

概念位置

對擴充開放與對修改封閉看起來互相矛盾：要讓模組有新的行為，通常就得改它。Robert C. Martin 在 1996 年的〈The Open-Closed Principle〉裡給的解法是「抽象是關鍵」：使用端只依賴一個固定的抽象（例如一個介面或抽象類別），新的行為由新的實作提供。使用端依賴的抽象不變，所以使用端不必修改；實作可以一直增加，所以行為可以擴充。用單一職責原則的語言說，單一職責原則畫出模組的邊界，抽象是這條邊界上對外公開的部分，各個實作留在邊界內，其他模組不需要知道。

同一篇文章另有一段〈Strategic Closure〉，是這條原則的使用條件：沒有一個有規模的程式能百分之百封閉，不論模組多「封閉」，總有某一類變更是它擋不住的。Martin 的例子是一個依序畫出所有圖形的函式，它對「新增一種圖形」封閉，對「先畫完所有圓形再畫方形」這種順序規則的變更就不封閉。所以封閉要有選擇：設計者要挑出要封閉的那幾類變更，Martin 給的依據是對使用者與產業的了解，判斷哪幾類變更最可能發生。

「封閉要有選擇」這個條件讓開放封閉原則與 Divergent Change（發散式變更） 接在一起：修改紀錄是「哪幾類變更最可能發生」最直接的證據。一類變更在紀錄裡已經反覆發生、每次都要改同一個模組，就是 Divergent Change 的形態，也是值得封閉的候選。替紀錄裡從沒出現過的那一類變更預先做擴充點，現在就要多寫並維護一層抽象，換到的是一個未必發生的變更變便宜；這是 YAGNI 處理的那種取捨，它在什麼條件下成立見 YAGNI 的真實適用條件。

可觀察訊號與例子

需要開放封閉原則的訊號，是同一類變更反覆要求修改同一段程式碼：

• 依類型分支的函式：一個 if 或 switch 依格式（PDF、Excel、HTML）或類型分派，每新增一種格式就要在這段程式碼裡多加一個分支，並重新確認沒有改壞其他分支。改成每種格式各一個實作、使用端只依賴共同的抽象之後，新增格式變成新增一個實作。
• 集中登記檔：新增一種實作之後，還要回到一份集中的清單登記它。這份清單仍然對「新增實作」不封閉，並行的需求也會在它的尾端同時追加而衝突（處置見從修改紀錄畫模組邊界〈熱點的分類與處理方式〉）；用自動登記（依命名規則或目錄掃描）可以讓這份清單也不必再改，代價是登記關係不再寫在一個看得到的地方。
• 共用的全域狀態：Martin 在同一篇文章裡指出，依賴全域變數的模組，對任何可能改寫那個變數的模組都無法封閉；依賴那個全域變數的模組很少、或那個全域變數不可能被不一致地使用時，損害才小。

各語言的寫法不同：Python 用抽象基類或 Protocol，Go 用 interface，Dart 用 abstract class。Python 的例子在開放封閉原則與認知負擔。

設計責任

套用開放封閉原則的設計責任是選對要封閉的變更。判斷問句是：這個擴充點要擋的那一類變更，在過去的修改紀錄裡發生過幾次，三種結果各有處置：

• 已經反覆發生（紀錄裡有兩次以上、每次都改同一處）：做擴充點。
• 只發生過一次：看對使用者與產業的了解判斷它會不會再發生——例如報表格式由客戶要求、而客戶還會再要新格式——判斷會再發生才做；判斷不出來就先照原樣改，等它第二次發生。
• 從沒發生過：先不做。

擴充點做出來之後，抽象本身成了很多實作共同依賴的對象，修改抽象的成本隨實作數增加，所以抽象只放那一類變更裡每個實作都需要的操作，不放眼前某一個實作才有的細節。

概念位置

DRY 管的對象是知識，不是程式碼的字面。2019 年的第二版特別說明，很多讀者把 DRY 讀成「不要複製貼上程式碼」，而 Hunt 與 Thomas 指的是知識與意圖的重複：同一件事寫在兩個地方，即使兩處的寫法完全不同（一段程式碼與描述它的文件、一份資料庫綱要與對應的資料結構），也是重複。

反方向也成立：兩段字面相同的程式碼，如果因為不同的理由改變，就不是同一份知識。Single Responsibility Principle（單一職責原則）的判斷在這裡接手：兩段程式碼要求的改動屬於不同種類（一段跟著某個職能的規則變、另一段跟著另一個職能的規則變），現在相同只是碰巧，合併成一個共用函式之後，為其中一個需求做的修改會改到另一個需求依賴的行為，那個共用函式就成了 Divergent Change（發散式變更）。Martin 在《Clean Architecture》的單一職責那一章把這種字面相同、理由不同的情形稱為 accidental duplication（意外的重複）。

可觀察訊號與例子

需要套用 DRY 的訊號，是同一份知識的變更要同時改好幾處：

• 同一條規則複製在好幾個檔案：例如四個腳本各自寫了一份相同的 git 指令包裝函式，要改一個 git 指令選項就得改四次。四份都因同一個理由改變（呼叫 git 的方式），是同一份知識，所以抽成一個共用函式、四處改成呼叫它。Python 專案的做法與遷移順序在 DRY 原則與共用程式庫。
• 同一個常數寫在好幾處：例如逾時秒數同時寫在程式碼、設定檔與文件裡。保留一個權威來源（通常是程式執行時實際讀取的那一處，例如設定檔），程式碼讀它、文件連到它。
• 程式碼與文件描述同一件事：文件抄了一份參數清單，程式碼改了而文件沒改。讓文件從程式碼產生，或文件只寫程式碼表達不了的部分。

判斷兩段相似的程式碼要不要合併時，Martin Fowler 在《Refactoring》引述 Don Roberts 的 Rule of Three：第一次照寫，第二次寫出相似的程式碼時先容忍重複，第三次才抽出共用的部分。Rule of Three 決定的是什麼時候判斷，要不要合併仍由下一節的判斷問句決定：等到有三份相似的程式碼，才累積得出足夠的修改紀錄，看得出它們是不是一起改。

設計責任

套用 DRY 的設計責任是讓每一份知識只有一個權威來源，而合併之前先確認那幾段程式碼是同一份知識。判斷問句是：這幾處過去的修改，是否每次都一起改、而且由同一個需求驅動；兩個條件都成立才是同一份知識，合併；任一個不成立，字面相同也分開保留。合併之後，函式裡開始需要一個參數來分支成兩套行為，代表那兩套行為各自由不同的理由改變，是合併錯了的訊號。

概念位置

內聚依「這些元素為什麼放在一起」分成幾種。由弱到強的排序依據是放在一起的理由與模組那件工作的關係有多緊：偶然內聚的元素之間完全無關，功能內聚的每個元素都屬於同一件工作。

• 偶然內聚（coincidental）：放在一起沒有任何理由，例如一個什麼都放的 utils 模組。
• 邏輯內聚（logical）：元素屬於同一個類別，例如所有輸入處理都放在一起，而每一種輸入的處理彼此無關。
• 時間內聚（temporal）：元素在同一個時間點執行，例如程式啟動時要做的所有初始化。
• 程序內聚（procedural）：元素總是依某個順序執行。
• 通訊內聚（communicational）：元素操作同一份資料。
• 循序內聚（sequential）：一個元素的輸出是下一個元素的輸入。
• 功能內聚（functional）：所有元素一起完成一件定義明確的工作。

Robert C. Martin 在《Agile Software Development》的單一職責那一章寫明，這條原則在 Tom DeMarco 與 Meilir Page-Jones 的著作裡已有描述，「They called it cohesion」，他們把內聚定義成模組元素在功能上的相關程度；Martin 在那一章把內聚的意思稍微移動，改成和「讓模組改變的力量」相關。兩種判斷用到的資訊不同：功能相關看程式碼在做什麼，單一職責原則看誰會要求它改變。兩種判斷可能給出不同結果：一個模組完成一件定義明確的工作，屬於功能內聚；如果那件工作的規則由兩個業務職能各管一半，它仍然有兩個改變的理由。決定要不要拆時以改變的理由為準，內聚的層級用來描述元素放在一起的理由屬於哪一種。

可觀察訊號與例子

低內聚的模組有幾個可以觀察到的訊號：

• 名字說不出它做什麼：utils、helpers、common、misc 這類名字通常代表偶然內聚，裡面的函式彼此沒有關係，只是沒有更好的去處。
• 改一處要讀整個模組，而讀到的大部分與這次修改無關：模組裡混了幾群互不相關的元素。
• 修改紀錄裡同一個模組被不相干的需求輪流修改：這是內聚不足在版本歷史上的樣子，也就是 Divergent Change（發散式變更）。

反方向的錯誤是把同一件工作拆到好幾個模組，每個模組單獨看都很小，而那件工作的每一次修改都要同時改它們，這是 Shotgun Surgery（散彈式修改）。

設計責任

提高內聚的設計責任是讓模組裡的每個元素都因為同一個理由放在這裡，理由指的是改變的理由：它會因為哪一種改動而改變。判斷問句是：逐一寫出模組裡每個元素會被哪一種改動要求修改（那一類改動由哪一個職能決定）；同一種改動的那一群留下，屬於別種改動的、或寫得出的原因只有「沒有別的地方放」的，移到它所屬的模組。移完之後回頭看 Coupling（耦合）：移出去的元素如果仍然大量讀寫原模組的內部資料、而且每次修改都要和原模組一起改，那個元素與原模組本來就屬於同一個模組，移出去的判斷錯了。

概念位置

耦合依兩個模組共享的內容分成幾種，由強到弱是：

• 內容耦合（content）：一個模組直接使用另一個模組內部的程式碼或資料，例如跳進對方的內部、改對方的私有欄位。
• 共用耦合（common）：好幾個模組存取同一份全域資料。
• 外部耦合（external）：模組共用一個外部規定的資料格式、通訊協定或裝置介面。
• 控制耦合（control）：一個模組傳一個旗標給另一個模組，由旗標決定接收的模組要走哪一條邏輯。
• 戳記耦合（stamp，其他中文資料也寫作「標記耦合」）：模組之間傳遞一整個複合資料結構，而接收的一方只用到其中一部分欄位。
• 資料耦合（data）：模組之間只透過參數傳遞需要的資料。

耦合越強，一個模組的修改越可能要求另一個模組跟著改。Open-Closed Principle（開放封閉原則）用來降低耦合的手段是讓使用端只依賴一個固定的抽象：使用端與各個實作之間只剩下對那個抽象的依賴，實作的內部改變不會傳到使用端。

可觀察訊號與例子

耦合過強的訊號，是修改一個模組時發現要同時改另一個模組，而這次修改的需求只跟被修改的那個模組有關：

• 改一個模組的內部欄位，另一個模組編譯失敗或行為改變：另一個模組直接讀寫了這些欄位，是內容耦合。
• 改一份全域設定，幾個看似無關的模組行為都變了：它們共用同一份全域資料，是共用耦合。Martin 對全域變數的說明在 Open-Closed Principle 卡片。
• 函式收一個 mode 或 is_xxx 參數，依它切換成完全不同的兩套行為：呼叫端在控制被呼叫端的流程，是控制耦合；這種函式通常也代表兩套行為各自有不同的改變理由，拆成兩個函式之後，呼叫端直接呼叫它要的那一個。
• 函式收一整個物件、只讀其中一兩個欄位：例如計算運費的函式收整個訂單物件，只讀了寄送地址。訂單物件的結構一改，運費函式就要重新確認，是戳記耦合；測試這個函式時也得先造出一整個訂單物件。改成只收寄送地址，就降成資料耦合。

兩個模組之間有耦合本身不是錯誤，模組要合作就一定要交換資料或呼叫對方。要確認的是交換的內容是否只有完成這次呼叫實際用到的資料。

設計責任

降低耦合的設計責任是讓模組之間只交換合作需要的資料，而且依賴的方向穩定。判斷問句是：改這個模組時，有哪些別的模組要跟著改，原因是什麼；原因是那些模組讀了這個模組的內部、共用了同一份可變資料、或用旗標控制這個模組的流程，就把那份依賴改成更弱的形式，依情形選一種：只傳它實際用到的資料（降成資料耦合），或改成依賴一個抽象（做法見開放封閉原則）。降低耦合之前先確認那兩個模組是否本來就該是同一個：兩者過去的修改幾乎每次都一起發生，或一方大量讀寫另一方的內部資料，拆成兩個模組只會讓每次修改都要改兩處，形成 Shotgun Surgery（散彈式修改）。這時把兩者合併成一個模組比降低它們之間的耦合更合適，合併之後它們放在一起的理由相同，內聚也隨之提高。

子分類與排序

分類的範圍與相鄰分類

• 本分類的兩個系列都不依賴任何語言的實作；各語言的寫法放 程式語言，那裡的系列引用本分類的定義，路由是單向的。
• 畫面狀態與互動設計放 UX Design，跟本分類共用的只有「設計」這個字。

Backlog

目前沒有待辦項。