消除你程式碼的臭味 Day 13- 魔術數字：用具備語義的常數取代

數字本身不會說話，名稱會。

在程式碼裡看到一個像 86400 或 0.05 這樣的數字，看到的不是一個值，看到的是一個問題。

這個數字是從哪裡來的？它代表什麼？如果它需要改變，我還需要去改其他哪些地方？

這裡留下了一顆未爆彈，讓下一個維護者去猜，猜錯了，系統就發臭跟炸了。

看不懂的數字都是風險。

經典案例：到處都是看不懂的數字

// 🔴 臭味：這不是程式碼，這是考古學。你需要猜測古人是什麼意思。
function calculateTotal(price) { 
  return price * 0.08 + 60; 
}

• 它無法被理解： 沒有上下文，這行程式碼就是濃濃的臭味。必須去問別人，或者翻遍整個系統，才能猜出這兩個數字的含義。

• 它無法被維護： 明年，政府把稅率從 8% 改成 9%。要怎麼辦？全域搜尋取代 0.08？萬一系統裡還有另一個 0.08 代表的是「8% 的佣金」呢？。

• 它極易出錯： 另一個開發者在另一個檔案裡也需要計算運費，但他記成了 65。現在，你的系統裡就有了兩種運費標準，而你對此一無所知，直到客戶打電話來罵人。

用常數表達意圖

// 🟢 好味道：程式碼在陳述事實，而不是在念咒。

// 這是一個集中管理的地方，是系統中關於費率的「單一事實來源」。
const TAX_RATE = 0.08;        // 營業稅率
const SHIPPING_FEE_TWD = 60;  // 基本運費 (台幣)

function calculateTotal(price) { 
  const tax = price * TAX_RATE;
  const total = price + tax + SHIPPING_FEE_TWD;
  return total; 
}

• 程式碼即文件： TAX_RATE 和 SHIPPING_FEE_TWD 這兩個名字，比任何註解都更清晰。程式碼自己解釋了它在做什麼。

• 維護的信心： 當稅率改變時，只需要修改 TAX_RATE 這一個地方。可以 100% 確定這個修改是安全且全局有效可靠的。

• 消除不一致： 任何需要用到運費的地方，都必須引用 SHIPPING_FEE_TWD。這也防範了「有人記成 60，有人記成 65」的錯誤。

重構步驟

1. 盤點硬編碼數值與字串。
2. 加入語意命名與單位，移至常數檔。
3. 用自動化搜尋取代所有呼叫點。
4. 在 PR 中新增「常數變更說明」小節。

常數的命名指引

1. 命名它的「目的」，而不是它的「值」。

   • const MAX_LOGIN_ATTEMPTS = 5; 是好的。
   • const FIVE = 5; 是極度愚蠢的。名字必須解釋為什麼這個數字存在。

2. 為單位命名。

   • 如果一個數字有單位，把它寫進名字裡。
   • TIMEOUT_MS、BUFFER_SIZE_KB、DEFAULT_MARGIN_PX。不要讓別人猜單位。

3. 集中管理。

   • 把所有業務規則、環境參數相關的常數都放在一個或幾個特定的檔案裡 (config.js, constants.sh 等)。
   • 這個檔案本身就成了一份極佳的系統設定總覽。

檢查清單

1. 是否有硬編碼數字或字串？
2. 是否能用具名常數或列舉型別表達？
3. 常數是否集中管理？
4. 命名是否貼近領域語言？
5. 你在六個月後看到這個數字，能立刻明白它的用途嗎？

今日重點

• 用名稱取代神祕數值。
• 集中管理，避免分散。
• 讓意圖清楚，維護更輕鬆。

一個沒有名字的數字，是欠下的一筆技術債。
一個有名字的常數，是為程式碼的清晰性和穩定性做出的一項投資。