Phase 4: 文件大整頓 — 當理想碰上現實的對帳時刻
這次做了什麼?
這次的工作其實沒有寫什麼新功能,反而是回頭看自己做了什麼 — 一個很重要但容易被忽略的「對帳」工作。
經過前三個 Phase 的快速開發後,我開始覺得不太對勁:明明已經重寫了一堆模組,但文件裡的狀態表卻跟實際情況對不上。有些模組明明已經提交了,狀態還是 ❌;有些模組的檔案數量怎麼看都不對勁。更重要的是,經過 AssetHub 的大改造後,我發現原本訂的「重寫規則」已經不太夠用了。
所以這次主要做了三件事:
-
把
eas-rewrite-plan.md文件拆分重組 — 原本的計畫文件越寫越長,模組狀態列表就佔了一大半。現在把狀態列表獨立成eas-module-status.md,計畫文件裡改放連結,看起來清爽多了。 -
更新重寫規則 — 經過 AssetHub 的實戰經驗,我發現「核心邏輯不變」這個規則太嚴格了。實際上我需要的是「公開 API 相容」,內部架構怎麼改都可以。還新增了 Bug 修正規則、新功能處理規則,以及把差異化手法分成「程式碼層級」和「架構層級」兩種。
-
全面核對模組狀態 — 用 git ls-files 把所有已追蹤的檔案都撈出來,一個一個比對文件上的記錄。結果發現一堆錯誤…
用了哪些技術?
這次主要用的是最樸實無華的 Git 命令 和 手動核對。
Git 檔案追蹤檢查
我用了這個指令來找出所有已提交的 .cs 檔:
git ls-files "Assets/EAS/eas-foundation/Editor/**/*.cs" "Assets/EAS/eas-foundation/Runtime/**/*.cs"這個指令會列出所有被 Git 追蹤的檔案,然後我再跟文件上的狀態列表比對。結果發現好幾個模組的狀態根本就是錯的。
檔案數量驗證
對於每個模組,我用類似這樣的指令來數檔案:
git ls-files "Assets/EAS/eas-foundation/Editor/Extension/*.cs" | wc -l這才發現 Extension 模組文件上寫 7 個檔案,實際上有 10 個 — 漏掉了 StyleBuilder、PathItem、ReorderableTable 三個重要工具。
Markdown 文件結構設計
在拆分文件時,我採用了 單一職責原則:
eas-rewrite-plan.md→ 負責「規則、流程、指導方針」eas-module-status.md→ 負責「狀態追蹤、數據統計」
兩個文件用連結互相引用,保持文件之間的關聯性,但各自獨立維護。這樣以後要更新狀態時,就不用在一大堆規則說明裡找數字了。
遇到什麼挑戰?
挑戰 1: 文件跟現實對不上
最尷尬的就是發現文件上寫著 ❌ 未完成,但實際上檔案早就提交了。
像是 ConstKeyGenerator 這個模組,我在 Phase 1 就已經提交了 (commit 1eab772),但狀態表上還是 ❌。還好有 Git 歷史可以查,不然我可能會以為自己沒寫過…
更糟的是檔案數量錯誤。像 Extension 模組,文件上寫 7 個檔案,實際上有 10 個。這代表我在記錄的時候可能只數了一部分,或是後來新增了檔案忘記更新。這種錯誤很容易讓人誤判進度。
解決方法: 現在我學乖了,每次提交後一定要馬上更新狀態文件。而且要用 Git 命令驗證,不要光憑記憶。
挑戰 2: 規則不夠彈性
原本的規則 2 寫著「核心邏輯不變,不重新設計實作方式」,但在重寫 AssetHub 時,我發現這根本行不通。
舊的 AssetHub 是用繼承體系 (Provider → IAssetProvider),但這個設計很糟糕,違反開放封閉原則。如果我堅持「核心邏輯不變」,就得繼續用這個爛設計。但這樣重寫還有什麼意義?
所以我把規則改成:「公開 API 相容,內部架構可以大改」。只要對外的使用方式不變,裡面怎麼重構都可以。這樣才能真正改善程式碼品質。
解決方法: 把規則從「邏輯不變」改成「API 相容」。同時新增了「差異化手法」的分層:程式碼層級的改進 (效能、可讀性) vs 架構層級的改進 (設計模式、相依性)。前者可以自由發揮,後者需要討論確認。
挑戰 3: 數字對不上的焦慮
當我發現檔案數量對不上時,心裡其實有點慌。我會想:「是不是哪裡算錯了?會不會有檔案漏掉沒提交?」
後來發現主要是兩種情況:
- 多計: 像 CheckTool 文件上寫 6,實際只有 4。可能是算了測試檔或暫存檔。
- 漏計: 像 Extension 寫 7,實際有 10。可能是後來新增的檔案忘記更新數字。
這種數字錯誤雖然不會影響程式運作,但會影響進度判斷。如果數字不準,就不知道還剩多少工作量。
解決方法: 建立了一個標準流程 — 每次更新狀態時,一定要用 Git 命令重新數一次檔案,不要相信舊數字。現在文件上的數字都是用指令確認過的。
挑戰 4: 要不要記錄移除的檔案?
在核對過程中,我發現有些檔案被移除了 (像 Timer 相關的檔案)。一開始不確定要不要記錄這些。
後來決定還是記錄下來,因為這些資訊很有價值:
- 知道哪些功能被移除了,避免以後又重複實作
- 了解為什麼移除 (例如 Timer 可能是被更好的方案取代)
- 統計時可以知道真正的工作量 (不是所有舊檔案都會被保留)
解決方法: 在狀態文件中新增「移除清單」段落,記錄所有被移除的檔案及原因。
學到了什麼?
經驗 1: 文件要即時更新
以前總覺得「等一批功能都做完再一起更新文件就好」,結果就是文件越來越不準。現在學到:每次 commit 後就馬上更新狀態,趁記憶還新鮮。
經驗 2: 用工具驗證,不要相信記憶
人的記憶會出錯,尤其是處理幾十個模組、上百個檔案時。Git 命令不會騙人,每次更新數字前先用命令確認一次,才能保證準確。
經驗 3: 規則要從實戰中提煉
一開始訂的規則往往不夠完整,因為你還沒遇到各種狀況。經過幾次實戰後,就會知道哪些規則太嚴格、哪些情況沒考慮到。要勇於調整規則,不要被一開始的設定綁死。
經驗 4: 對帳很重要
這次對帳發現了好幾個錯誤,讓我意識到:定期停下來核對現狀很重要。不要一直埋頭往前衝,偶爾要回頭看看「我真的在做對的事嗎?進度有沒有偏離?」
目前進度
經過這次全面核對,現在的狀態是:
- 已提交: 約 122 個 .cs 檔 (49 Editor + 73 Runtime)
- 未提交: 約 55 個 .cs 檔 (13 Editor + 42 Runtime)
- 特殊處理: 跳過 4 檔 + 移除 18 檔
換句話說,大約完成了 69% 的檔案重寫工作 (122 / 177)。
下一步
現在文件已經整理乾淨,規則也更新完畢,接下來可以繼續推進剩下的 55 個檔案。
但我不會急著全部寫完,而是會按照優先順序來:
- 先處理核心功能相關的模組 (例如 Service、Event 系統)
- 再處理編輯器工具 (這些通常比較獨立,可以分批處理)
- 最後處理輔助工具和 Extension (這些可以慢慢補)
重要的是保持文件與現實同步,不要再讓它們失聯了。
→ 繼續閱讀：[[專案/EAS Foundation/日誌/#05-Editor工具大補包-樹狀檢視與字典編輯器的誕生|#05 Editor 工具大補包]]