降低 Python 複雜度
檔案:$ARGUMENTS
程式碼複雜度宜保持低水平。複雜度以 Python 詞彙 Token 中屬於強制式程式碼(即執行某種動作的語法)的數量來衡量。宣告是用來組織程式碼的,不會增加邏輯,因此不計入。
哪些算在內
定義方式請見與此檔案同目錄的 imperative_tokens.py。
不計入:
def和class的標頭,從第一個裝飾器到冒號(主體開頭):裝飾器、參數、預設值、基底類別、回傳型態註記。這一切只在定義時計算一次,並宣告一個介面。- 型態註記(
x: int = 1視為x = 1,x: int視為無)、type別名。 - 匯入、註解、文件字串、換行與縮排。
- 呼叫中的關鍵字參數名稱:
f(key=value)與f(value)權重相同。在大部分情況下,建議使用關鍵字傳遞引數,因此不計成本。 - 屬性限定:
a.b.c.d與d權重相同。點狀路徑只命名一個物件。若將其計入,將獎勵from numpy import log勝過np.log,或為self.x建立本地別名,而這兩者都不會改變任何邏輯。
計入: 所有其他 Token。陳述式(if、for、while、try、with、return、raise……)、賦值、運算子、呼叫、字面值、推導式與 Lambda,以及它們的逗號、冒號和成對括號中的任一個。因此,一個呼叫比執行相同動作的運算子多 1 個 Token:a.update(b) 是 4 個 Token,a |= b 是 3 個。
對於筆記本 (.ipynb),只計算程式碼儲存格。魔術或 Shell 指令行(%config …、!pip …)視為 IPython 將其轉換成的呼叫。位於儲存格魔術(%%bash、%%html)下的儲存格計為 0。例外情況是執行主體為 Python 的儲存格魔術(IPython 的 ExecutionMagics,例如 %%time 和 %%capture):魔術部分計為一行魔術,主體則計為程式碼。非 IPython 內建魔術(例如來自擴充套件)計為 0,指令稿會印出警告:請在報告中傳遞該警告。核心非 Python 的筆記本計為 0。指令稿僅在處理 Python 筆記本時才匯入 IPython,並向它詢問哪些魔術是內建的。
Token 數量只是代理指標
Token 數量降低是簡化的證據,而非簡化本身。
- 允許重大重構: 新增輔助函式、新增基底類別、新增檔案。此時會比較所有受影響檔案的總和(步驟 4),因此在檔案間移動邏輯會相互抵銷。
- 需要自行提出理由: 將邏輯移到指令稿不會檢查的地方(如預設值、裝飾器引數、基底類別表達式或新的相依套件)。提案需解釋為何此變更除了降低 Token 數之外,還是好的。
- 禁止: 將程式碼放入字串中透過
eval、exec或類似的外部執行方式來執行。 - 內聯只使用一次的變數 只有在不損害可讀性的情況下才可接受。為中間變數取一個好名稱有助於讀者理解意圖。
- 不視為降低: 移除行為(邊界驗證、錯誤處理、支援的情況),以及為了減少幾個 Token 而犧牲可讀性(密集的單行、移除結尾逗號)。
專案本身的規則(CLAUDE.md、編碼規範)優先於 Token 數量。
非嚴格等價的變更
若變更為了簡化而改變行為,但能論證程式仍保持正確,則允許。提案需說明何處不同、針對哪些輸入,以及論證及其在程式碼中的證據:
- 此不同的輸入不可能發生。 證據:建構或驗證該值的程式碼。
- 沒有人會觀察到此差異。 證據:列出該值的每個消費端。
- 此差異可觀察但無害: 例如取自播種隨機產生器、較慢的演算法、提前引發的錯誤。這需要使用者明確同意。任何公開回傳值、寫入輸出或測試能看到的差異也同樣需要使用者同意。
以下是一些範例,說明論證的形式。任何其他改變行為的變更都應以相同方式論證,不論是否與以下範例類似:
| 簡化形式 | 取代 | 差異點 |
|---|---|---|
x or default | x if x is not None else default | 會將假值 x(0、""、[])也取代掉 |
zip(a, b) | 透過 range(len(a)) 對兩者索引 | 較短的 b 會無聲截斷;strict=True 保留此檢查 |
| a // b | int(a / b) | 負數運算元會朝不同方向四捨五入 |
| max(xs, key=f) | sorted(xs, key=f)[-1] | 平手時,第一個相等項目勝出,而非最後一個 |
| xs.sort() | xs = sorted(xs) | 呼叫者傳入的串列被修改(就地排序) |
| Counter(xs) | 計數迴圈 | 讀取缺失的鍵會回傳 0,而非引發例外 |
以 @dataclass 定義,用 row.name 讀取 | 以 dict 記錄,用 row["name"] 讀取 | 索引、.get、** 解包與 JSON 序列化將失效 |
論證必須基於程式碼,而非今日的資料:「此檔案沒有重複資料」不是有效論證,「可能唯一」也不是。移除行為(如邊界驗證)仍屬排除範圍,不能透過論證來規避。
不確定時,由使用者決定。 若證據不完整(消費端在儲存庫之外、無法讀取建構值的程式碼),或不確定某個差異是否無害,則不要自行定案。提供該變更以及差異點與未知的部分,繼續處理其他提案,並僅在使用者同意後才套用該變更。
標準函式庫形式
以下是一些常見情況的範例,說明這類取代的樣貌。這並非完整目錄:內建函式、標準函式庫與專案已安裝的相依套件提供了更多選擇,表格中未列出的取代方式也同樣有效。
| 標準形式 | 取代 | 差異點 |
|---|---|---|
@dataclass,搭配 field(default_factory=list)、order=True、frozen=True | 僅儲存參數的 __init__;手寫的 __eq__、__repr__、__lt__、__hash__ | 原先沒有 __eq__ 的類別現在會以值比較且無法可雜湊(eq=False 保留身份比較);__eq__ 也會比較類別;明確的 None 不再成為預設值 |
any(p(x) for x in xs)、all(…)、next(filter(p, xs), None) | 帶 break 的旗標或搜尋迴圈 | 無 |
defaultdict(list) | if key not in groups: groups[key] = [] | 讀取缺失的鍵會插入該鍵 |
@cache、@cached_property | 記憶字典;if self._x is None 惰性屬性 | 在方法上使用 @cache 會保持它呼叫過的每個實例存活;此屬性需用 del 重置,而非賦值為 None |
itemgetter("foo")、str.strip、operator.mul | 只索引、只呼叫一個方法或只套用一個運算子的 Lambda | str.strip 在非字串值上會引發例外 |
Path(path).read_text() | with open(path) as file: 與 file.read() | 無 |
name.removeprefix(prefix)、line.partition("=") | startswith 與切片;split 與長度檢查 | 無 |
chain.from_iterable(xss) | [x for xs in xss for x in xs] | 迭代器:若結果會被索引或讀取兩次,請用 list 包裝 |
batched(xs, n) | 在 range(0, len(xs), n) 上使用 xs[i:i + n] | 回傳元組迭代器,而非切片串列 |
@singledispatch | isinstance 鏈 | 最特定的註冊類別勝出,而非第一個符合的測試;分發的引數是第一個,以位置傳遞 |
@singledispatch 與 @dataclass 的引數會將邏輯移到標頭中,而這是指令稿不會檢查的地方。它們除了 Token 數之外的理由:產生的方法會遵循欄位清單,不會偏離;每個型別都有專屬的函式,新增型別時不會影響到現有函式。
其他形式只有在特定上下文下才有幫助,因此需要額外考量:
itertools.product或itertools.combinations可以取代巢狀迴圈。functools.reduce可以取代沒有內建函式的摺疊操作。
步驟
-
基準線。 使用專案的 Python 解譯器(Python 3.12 或更新版本)對引數中的檔案執行指令稿,並保留輸出:
python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <file.py | notebook.ipynb> [...]立即執行測試:在變更前就失敗的測試套件無法驗證變更後的任何內容。如果使用者只要求測量,則回報結果並停止。
-
提案。 閱讀程式碼以理解其計算的內容,而非尋找可匹配的模式。對於每個函式、迴圈與分支,拷問是否能用更少的 Token 表達相同的結果。此技能中的串列與表格展示了簡化的樣貌。但這些並非搜尋空間:大部分可以刪除的內容都是特定於該程式碼的,沒有任何串列能預先涵蓋。僅檢查所列模式的遍歷是不完整的。
常見的發現,大致按產出排序:
- 死程式碼:未使用的函式、參數與無法到達的分支;
- 相同邏輯寫了兩次(在此檔案或其他檔案中),可用共用的輔助函式或基底類別保留一份;
- 手寫的程式碼,但標準函式庫、內建函式或已安裝的相依套件已提供;標準函式庫工具如
itertools、functools、operator、collections或dataclasses可能有幫助,上述「標準函式庫形式」列出了常見情況; - 建構值的迴圈:推導式通常優於迴圈,偶爾
filter或map內建函式比推導式更簡單; - 可被重載運算子取代的方法呼叫:
a | b取代a.union(b)、a |= b取代a.update(b)、a @ b取代a.dot(b)。先檢查運算元型別:對集合使用|=需要集合,而.update()接受任何可迭代物件; - 可折疊為資料結構(對應表)或一般路徑的分支;
- 僅為了被撤銷而存在的狀態與轉換;
- 遠離程式邊界的防禦性檢查;
- 比其輸入需求更嚴格的程式碼,其中較簡單的形式僅在不可能發生或無人觀察的輸入上有所不同(上表)。
然後再次檢查整個程式碼,先處理最長的函式,尋找不屬於上述任何一類的內容:不同的演算法或資料結構,使簿記變得多餘;重新安排計算順序,使特殊情況消失;專案已使用的相依套件中的某個函式可以完全勝任;兩個函式僅在一個值上不同。此類提案與任何列出的提案遵循相同規則。
若要評估一段程式碼(例如提案前後的幾行),可將其透過管線傳送給指令稿,而不指定檔案引數。它會只印出 Token 數。該程式碼片段必須能獨立解析,因此請移除縮排:
python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <<'EOF' uncounted |= set(range(first, last)) EOF每個提案應以程式碼形狀呈現,列出前後關鍵行、預期減少的 Token 數、影響的其他檔案,以及上述章節要求的任何理由或論證。在使用者同意後套用,或若使用者已要求直接進行變更,則可直接套用。
-
套用與驗證,一次一個提案,以便失敗時能指出原因。
- 在首次編輯基準線中未包含的檔案之前,先測量該檔案並將其加入基準線。新檔案從 0 開始。
- 測試必須通過且未經修改。與其檢查的程式碼一起被編輯的測試不再能檢查該程式碼;若測試必須修改(例如它呼叫了被移除的輔助函式),請說明。
- 從未執行變更後程式碼的測試無法證明任何事。對於這些程式碼行,在相同輸入(包含邊界情況)上分別執行舊版本(
git stash,或git show HEAD:<path>到暫存檔案)與新版本,並比較輸出。浮點數結果必須相同,否則報告需說明差異的大小。 - 非嚴格等價的變更,必須在其論證所允許的輸入上進行比較。然後檢查論證本身:閱讀建構該值的程式碼,或搜尋每個消費端。無法成立的證據將導致提案被否決。
- 公開行為(簽名、例外型別、輸出的順序)的變更不屬於等價變更。需要使用者明確同意。
-
重新測量。 對所有受影響的檔案執行指令稿:包括引數中的檔案以及變更所編輯或建立的每個其他檔案。已刪除的檔案計為 0。合計總數必須低於合計基準線,否則還原變更。步驟 3 失敗的變更也同樣還原。
-
報告。 分別列出每個受影響檔案及合計結果:變更前後與差異的 Token 數。然後說明驗證等價性的方式(哪些測試、哪些直接比較)、每個非嚴格等價的變更(附上差異點與論證)、每個等待使用者決定的變更,以及每個被否決的提案(附上原因)。