ALL NOTES

LAB NOTES / 2026.10.23

程式碼拆分與重構|打敗程式碼的河馬大怪獸

(如果你點進來,是想知道什麼是河馬大怪獸,在文末~)

之前參加 iThome 鐵人賽的尾聲,回頭檢視 TaskTimer 的程式碼時,才驚覺單一檔案竟然變得如此冗長,維護時覺得很耗費心力,因此當時便決心進行了重構。(詳細的歷程可以參考這篇文章- DAY 31 | 東西擺整齊的療癒感!專案開發後的回頭重構與架構優化)

不過,一個檔案到底寫多少行程式碼才最剛好?在動手進行拆分與架構規劃時,究竟有什麼需要特別注意的呢?


在剛開始學寫程式時,因為練習的作業範圍比較小,通常會把所有 HTML、CSS 和 JavaScript 程式碼拆分成三個檔案。

一開始就這樣從頭寫到尾,觀察效果、功能是否有順利呈現,有達到預期的效果就好了。
但隨著自己開始做專案,畫面變多、功能增加,單一的檔案迅速擴張到幾百甚至上千行。當想改一個小按鈕的點擊行為時,卻得在密密麻麻的程式碼大海中捲動找半天,有時候改了 A 功能,結果 B 功能莫名其妙壞掉。(淚)

這時候,才深刻體會到 程式碼拆分(Code Splitting) 與 模組化(Modularization) 的重要性。


為什麼程式碼會變得難以維護?

在軟體開發中,如果程式碼缺乏良好的組織與拆分,通常會面臨以下幾個痛點:

1. 高耦合(High Coupling)

程式碼之間黏得太緊密。資料處理邏輯、畫面渲染、事件監聽通通混在一起,牽一髮而動全身。

2. 低內聚(Low Cohesion)

不相關的功能散落各處。想找某個特定功能的邏輯,必須同時翻好幾個不同的檔案或區塊。

3. 維護困難

過了一個月再回來看自己寫的程式碼,忘記自己當初這段在寫什麼。

實用的程式碼拆分心法與策略

為了讓程式碼好讀、好改、好擴充,我們在開發時可以把握幾個核心的拆分原則:

1. 單一職責原則(Single Responsibility Principle, SRP)

「一個函式或一個模組,只負責做好一件事情。」

  • 反面教材:寫一個超級大函式,裡面同時負責「從 LocalStorage 讀取資料」、「計算時間差」、「驗證使用者輸入」、「更新 DOM 畫面」。

  • 正確做法:把任務拆開。

  • 函式 A 專門處理資料計算。

  • 函式 B 專門處理畫面渲染。

  • 函式 C 專門處理事件監聽。

2. 檔案與邏輯的模組化拆分

隨著現代 JavaScript(ES6+)支援了 import 與 export 模組化語法,我們可以把程式碼分門別類放進不同的檔案裡:

1
2
3
4
5
6
7
📁 src/
┣ 📁 js/
┃ ┣ api.js <-- 專門負責資料請求與儲存 (LocalStorage)
┃ ┣ ui.js <-- 專門負責操作 DOM 與畫面更新
┃ ┣ timer.js <-- 專門處理計時核心邏輯
┃ ┗ main.js <-- 程式進入點,負責將模組組合起來
┗ 📁 css/

透過清晰的結構,當未來計時邏輯出問題時,我們可以在 timer.js 修正,而不需要去碰畫面的程式碼,大大降低了除錯的難度。

一個檔案到底寫多少行才好?

雖然沒有絕對硬性的標準,但在實務開發中,可以拿這些數字作為參考:

  • 理想範圍(約 100 - 200 行內):一個結構清晰、職責單一的模組或元件,通常在這個範圍內可以一目了然。

  • 注意警訊(超過 300 - 500 行):當檔案到這個長度時,通常代表這個檔案可能塞了太多不同的責任,這時候就建議考慮進行拆分了。

  • 極度危險(破千行):這就是典型的「河馬大怪獸」,捲動找程式碼需要很久,建議立刻著手重構。

不過,行數多寡也跟程式碼的性質有關(例如純粹的常數設定檔、型別定義檔稍微長一點沒關係),核心判斷依據依然是:「這個檔案是不是只負責一件事情?」

拆分過頭的陷阱:避免「過度設計」

雖然拆分程式碼好處多多,但有時候也會不小心掉入另一個極端– 過度設計(Over-engineering)。

如果專案比較小,硬是要把它拆成幾十個檔案、建立複雜的資料夾架構,反而會增加開發的負擔。


題外話 - 河馬大怪獸

關於河馬大怪獸,第一次登場是在我們講 i18n (語系切換|使用 data-i18n 實現多國語系的流暢切換) 的時候,當時提到一個很長的單字 : hippopotomonstrosesquippedaliophobia,意思是對長單字的恐懼。

它是透過 字根、字首、字尾 與 拉丁文/希臘文 組合而成的混合詞。

  • hippo-:源自希臘文 hippos,意思是「馬」

  • -potom-:源自希臘文 potamos,意思是「河」(合起來 hippopotamos 就是河馬)

  • -monstro-:源自拉丁文 monstrum,意思是「怪物、巨大的東西」

  • -sesquiplat- (sesquipedali-):源自拉丁文 sesquipedalis,字面上的意思是「一隻半腳長的」,在英文中引申用來形容「字句冗長的、喜歡用長單字的」

  • -phobia:源自希臘文 phobos,是英文中標準的「恐懼症」字尾

河馬雖然看起來圓滾滾,有一點笨重感,但其實他們是很有殺傷力的動物,除了在陸地狂奔時可以達到時速 40 公里之外,咬合力大概是獅子的三倍,可以輕易地把小船咬爆。建議大家還是要小心現實中和程式碼中的河馬(?

所有筆記