1Simple is better than complex.
2Complex is better than complicated.
3Special cases aren't special enough to break the rules.
4Although practicality beats purity.

 1# 階段 1：發現重複，提取函式
 2def process_user_data(data: dict) -> dict:
 3    """最初只處理使用者資料"""
 4    validated = validate_fields(data)
 5    normalized = normalize_strings(validated)
 6    return save_to_db(normalized)
 7
 8# 階段 2：「訂單資料也差不多嘛」，加入參數
 9def process_data(data: dict, data_type: str = "user") -> dict:
10    validated = validate_fields(data)
11    normalized = normalize_strings(validated)
12    if data_type == "order":
13        normalized = calculate_totals(normalized)
14    return save_to_db(normalized)
15
16# 階段 3：更多類型，更多分支
17def process_data(
18    data: dict,
19    data_type: str = "user",
20    skip_validation: bool = False,
21    custom_normalizer: Callable | None = None,
22    dry_run: bool = False,
23) -> dict:
24    if not skip_validation:
25        validated = validate_fields(data, strict=(data_type == "payment"))
26    else:
27        validated = data
28
29    if custom_normalizer:
30        normalized = custom_normalizer(validated)
31    else:
32        normalized = normalize_strings(validated)
33
34    if data_type == "order":
35        normalized = calculate_totals(normalized)
36    elif data_type == "payment":
37        normalized = encrypt_sensitive(normalized)
38    elif data_type == "inventory":
39        normalized = check_stock_levels(normalized)
40
41    if dry_run:
42        return normalized
43    return save_to_db(normalized, table=TABLE_MAP[data_type])

 1from abc import ABC, abstractmethod
 2
 3class DataProcessor(ABC):
 4    """定義處理流程的骨架，但不強制共用邏輯"""
 5
 6    @abstractmethod
 7    def validate(self, data: dict) -> dict: ...
 8
 9    @abstractmethod
10    def normalize(self, data: dict) -> dict: ...
11
12    @abstractmethod
13    def save(self, data: dict) -> dict: ...
14
15    def process(self, data: dict) -> dict:
16        validated = self.validate(data)
17        normalized = self.normalize(validated)
18        return self.save(normalized)
19
20class UserDataProcessor(DataProcessor):
21    def validate(self, data: dict) -> dict:
22        return validate_fields(data)
23
24    def normalize(self, data: dict) -> dict:
25        return normalize_strings(data)
26
27    def save(self, data: dict) -> dict:
28        return save_to_db(data, table="users")
29
30class PaymentDataProcessor(DataProcessor):
31    def validate(self, data: dict) -> dict:
32        return validate_fields(data, strict=True)
33
34    def normalize(self, data: dict) -> dict:
35        normalized = normalize_strings(data)
36        return encrypt_sensitive(normalized)
37
38    def save(self, data: dict) -> dict:
39        return save_to_db(data, table="payments")

 1# 可讀版本：清楚表達意圖
 2def find_active_premium_users(users: list[User]) -> list[User]:
 3    """找出活躍的付費用戶"""
 4    active_users = [u for u in users if u.is_active]
 5    premium_users = [u for u in active_users if u.plan == "premium"]
 6    recent_users = [u for u in premium_users if u.last_login > cutoff_date]
 7    return recent_users
 8
 9# 效能版本：單次遍歷，但意圖較不明顯
10def find_active_premium_users(users: list[User]) -> list[User]:
11    """找出活躍的付費用戶"""
12    return [
13        u for u in users
14        if u.is_active
15        and u.plan == "premium"
16        and u.last_login > cutoff_date
17    ]
18
19# 極致效能版本：犧牲可讀性
20def find_active_premium_users(users: list[User]) -> list[User]:
21    _is = True.__eq__  # 避免屬性查找
22    _pr = "premium".__eq__
23    _dt = cutoff_date
24    return [u for u in users if _is(u.is_active) and _pr(u.plan) and u.last_login > _dt]

 1# 決策流程（虛擬碼）
 2def should_optimize(code_section) -> str:
 3    # 步驟 1：有實際效能問題嗎？
 4    if not is_performance_bottleneck(code_section):
 5        return "維持可讀版本"
 6
 7    # 步驟 2：瓶頸在這裡嗎？
 8    profiling_result = profile(code_section)
 9    if profiling_result.time_percentage < 5:
10        return "瓶頸不在這裡，維持可讀版本"
11
12    # 步驟 3：有不犧牲可讀性的優化方案嗎？
13    if can_use_better_algorithm():
14        return "換演算法（通常不影響可讀性）"
15
16    if can_use_better_data_structure():
17        return "換資料結構（通常不影響可讀性）"
18
19    # 步驟 4：真的需要犧牲可讀性
20    return "優化，但加上詳細註解說明為什麼"

 1# 場景：頻繁的成員檢查
 2
 3# list -- O(n) 查找，但保留順序、允許重複
 4users_list: list[str] = ["alice", "bob", "charlie"]
 5if "alice" in users_list:  # 線性掃描
 6    pass
 7
 8# set -- O(1) 查找，但不保留順序、不允許重複
 9users_set: set[str] = {"alice", "bob", "charlie"}
10if "alice" in users_set:  # 雜湊查找
11    pass
12
13# 取捨考量：
14# - 集合 < 100 個元素：差異可忽略，選擇語義更清楚的
15# - 集合 > 10000 個元素且頻繁查找：set 是明確的選擇
16# - 需要保留順序 + 快速查找：dict.fromkeys() 或 OrderedDict

 1# 反面案例：自建 HTTP 請求函式庫
 2# 「我們只需要 GET 和 POST，寫一個很簡單」
 3import socket
 4
 5def simple_get(url: str) -> str:
 6    # 解析 URL、建立 socket、處理 SSL、
 7    # 處理重導向、處理分塊傳輸、處理超時...
 8    # 三個月後，你重新實作了 requests 的 30%
 9    # 但缺少了 cookie 管理、連接池、代理支援...
10    pass
11
12# 正確做法：用 requests 或 httpx
13import httpx
14
15response = httpx.get("https://api.example.com/data")

 1# 合理的自建案例：核心業務邏輯的定價引擎
 2# 這是你的競爭優勢，沒有通用方案能完全符合
 3class PricingEngine:
 4    """公司專有的定價策略，包含多年的業務經驗"""
 5
 6    def calculate(self, product: Product, customer: Customer) -> Price:
 7        base = self._base_price(product)
 8        adjusted = self._apply_customer_tier(base, customer)
 9        seasonal = self._seasonal_adjustment(adjusted)
10        return self._apply_regulatory_constraints(seasonal)

1# Fail Fast 風格：立即驗證，立即失敗
2def transfer_money(from_account: str, to_account: str, amount: Decimal) -> None:
3    if amount <= 0:
4        raise ValueError(f"轉帳金額必須為正數，收到: {amount}")
5    if from_account == to_account:
6        raise ValueError("不能轉帳給自己")
7    # ... 執行轉帳

 1# 預先驗證風格：收集所有錯誤後一次回報
 2def transfer_money(from_account: str, to_account: str, amount: Decimal) -> None:
 3    errors: list[str] = []
 4    if amount <= 0:
 5        errors.append(f"轉帳金額必須為正數，收到: {amount}")
 6    if from_account == to_account:
 7        errors.append("不能轉帳給自己")
 8    if not account_exists(from_account):
 9        errors.append(f"來源帳戶不存在: {from_account}")
10    if not account_exists(to_account):
11        errors.append(f"目標帳戶不存在: {to_account}")
12
13    if errors:
14        raise ValidationError(errors)
15    # ... 執行轉帳

1def process_batch(items: list[Item]) -> list[Result]:
2    # assert 適合標記「這裡不應該發生」的情況
3    assert items, "process_batch 不應該收到空列表"
4
5    # 但注意：python -O 會移除所有 assert
6    # 所以不要用 assert 做業務驗證
7    # 以下是錯誤用法：
8    assert user.is_authenticated, "使用者未登入"  # 不要這樣做

 1from typing import Protocol
 2
 3# 方案 A：嚴格的型別定義
 4class Serializable(Protocol):
 5    def to_dict(self) -> dict: ...
 6    def from_dict(cls, data: dict) -> "Serializable": ...
 7
 8def save_strict(obj: Serializable) -> None:
 9    data = obj.to_dict()
10    # ... 儲存
11
12# 方案 B：鴨子型別，依賴約定
13def save_flexible(obj: object) -> None:
14    if not hasattr(obj, "to_dict"):
15        raise TypeError(f"{type(obj).__name__} 缺少 to_dict 方法")
16    data = obj.to_dict()  # type: ignore
17    # ... 儲存
18
19# 方案 C：Protocol 的平衡點（推薦）
20# Protocol 提供靜態檢查，但不要求繼承
21class Persistable(Protocol):
22    def to_dict(self) -> dict: ...
23
24def save_balanced(obj: Persistable) -> None:
25    data = obj.to_dict()
26    # ... 儲存
27
28# 任何有 to_dict 方法的類別都自動滿足 Persistable
29# 不需要顯式繼承，保留了鴨子型別的靈活性
30class User:
31    def to_dict(self) -> dict:
32        return {"name": self.name}
33
34save_balanced(User())  # mypy 檢查通過，無需繼承

 1# 策略性技術債務：有意識地選擇，有計畫地償還
 2# 場景：MVP 需要在兩週內上線驗證市場
 3
 4# 目前的實作：直接用 JSON 檔案儲存
 5# 取捨決策：放棄資料庫，節省 3 天開發時間
 6# 償還計畫：驗證成功後第二個 sprint 遷移到 PostgreSQL
 7import json
 8from pathlib import Path
 9
10# TRADE-OFF: 使用 JSON 檔案而非資料庫
11# 原因: MVP 階段，使用者 < 100 人，讀寫頻率低
12# 風險: 無並行安全、無交易支援、效能隨資料量線性下降
13# 償還條件: 使用者 > 50 或資料 > 10MB 時遷移
14DATA_FILE = Path("data/users.json")
15
16def save_user(user: dict) -> None:
17    data = json.loads(DATA_FILE.read_text()) if DATA_FILE.exists() else []
18    data.append(user)
19    DATA_FILE.write_text(json.dumps(data, ensure_ascii=False, indent=2))

 1# 魯莽的技術債務：沒有意識到代價
 2# 場景：「先讓它動起來再說」
 3def handle_request(req):
 4    try:
 5        # 100 行沒有型別提示、沒有錯誤處理、沒有測試的程式碼
 6        data = req["data"]  # 可能是 None
 7        result = process(data)  # process 可能拋出任何異常
 8        db.save(result)  # 沒有交易管理
 9        return {"ok": True}
10    except:  # 裸 except：吞掉所有錯誤
11        return {"ok": False}

 1# 取捨評估模板
 2class TradeoffEvaluation:
 3    """用結構化方式記錄取捨決策"""
 4
 5    def __init__(self, decision: str):
 6        self.decision = decision
 7        self.options: list[dict] = []
 8
 9    def add_option(
10        self,
11        name: str,
12        benefits: list[str],
13        costs: list[str],
14        risks: list[str],
15        reversibility: str,  # "easy" | "moderate" | "difficult"
16    ) -> None:
17        self.options.append({
18            "name": name,
19            "benefits": benefits,
20            "costs": costs,
21            "risks": risks,
22            "reversibility": reversibility,
23        })
24
25    def evaluate(self) -> str:
26        """產出決策摘要"""
27        lines = [f"## 決策: {self.decision}\n"]
28        for opt in self.options:
29            lines.append(f"### 方案: {opt['name']}")
30            lines.append(f"- 可逆性: {opt['reversibility']}")
31            lines.append(f"- 優點: {', '.join(opt['benefits'])}")
32            lines.append(f"- 代價: {', '.join(opt['costs'])}")
33            lines.append(f"- 風險: {', '.join(opt['risks'])}")
34            lines.append("")
35        return "\n".join(lines)

 1# Type 2 決策：函式簽名可以之後改
 2# 先用簡單版本，有需要再擴展
 3def send_notification(user_id: str, message: str) -> bool:
 4    """現在只支援 email，之後可以擴展"""
 5    return send_email(user_id, message)
 6
 7# 之後需要時再擴展，改動成本很低
 8def send_notification(
 9    user_id: str,
10    message: str,
11    channel: str = "email",
12) -> bool:
13    """支援多種通知管道"""
14    sender = CHANNEL_MAP[channel]
15    return sender(user_id, message)

 1# Type 1 決策：資料庫 schema 設計
 2# 上線後很難改，需要仔細評估
 3
 4# 決策記錄（Architecture Decision Record）
 5# ADR-007: 使用者地址儲存方式
 6#
 7# 狀態: 已採納
 8# 日期: 2026-03-01
 9#
10# 背景:
11#   使用者可能有多個地址（家、公司、寄送地址）
12#
13# 考慮的方案:
14#   A. JSON 欄位：靈活但難以查詢和索引
15#   B. 獨立 address 表：標準化但查詢需要 JOIN
16#   C. 嵌入式欄位（home_addr, work_addr）：簡單但不可擴展
17#
18# 決策: 方案 B（獨立表）
19# 理由: 地址需要獨立查詢（物流系統需求），
20#        且未來可能增加地址類型

 1# 概念示意：基於重要性的取樣策略
 2import random
 3
 4# 不是所有請求都值得完整記錄
 5SAMPLING_RULES = {
 6    "health_check": 0.001,    # 0.1% -- 幾乎不需要
 7    "static_asset": 0.01,     # 1% -- 很少出問題
 8    "api_read": 0.1,          # 10% -- 標準取樣
 9    "api_write": 0.5,         # 50% -- 寫入操作更重要
10    "payment": 1.0,           # 100% -- 永遠完整記錄
11    "error": 1.0,             # 100% -- 錯誤永遠記錄
12}
13
14def should_sample(request_type: str) -> bool:
15    rate = SAMPLING_RULES.get(request_type, 0.1)
16    return random.random() < rate

1There should be one-- and preferably only one --obvious way to do it.

 1# 格式化字串：三種方式
 2name = "World"
 3
 4# % 格式化（最老，但 logging 模組仍在用）
 5message = "Hello, %s" % name
 6
 7# str.format()（Python 2.6+，某些場景更靈活）
 8message = "Hello, {}".format(name)
 9
10# f-string（Python 3.6+，通常是最佳選擇）
11message = f"Hello, {name}"

 1# 合併字典：多種方式
 2dict_a = {"a": 1}
 3dict_b = {"b": 2}
 4
 5# 方式 1：update（原地修改）
 6merged = dict_a.copy()
 7merged.update(dict_b)
 8
 9# 方式 2：解包（Python 3.5+，建立新字典）
10merged = {**dict_a, **dict_b}
11
12# 方式 3：聯集運算子（Python 3.9+，最 Pythonic）
13merged = dict_a | dict_b

 1# 階段 1：不加型別提示（快速原型）
 2def process(data):
 3    return [item["name"] for item in data if item.get("active")]
 4
 5# 階段 2：關鍵介面加型別提示（公開 API）
 6def process(data: list[dict[str, Any]]) -> list[str]:
 7    return [item["name"] for item in data if item.get("active")]
 8
 9# 階段 3：完整型別定義（長期維護）
10from dataclasses import dataclass
11
12@dataclass
13class Item:
14    name: str
15    active: bool = True
16
17def process(data: list[Item]) -> list[str]:
18    return [item.name for item in data if item.active]

 1# LBYL (Look Before You Leap) -- 先檢查再行動
 2def get_value_lbyl(data: dict, key: str) -> str | None:
 3    if key in data:
 4        value = data[key]
 5        if isinstance(value, str):
 6            return value
 7    return None
 8
 9# EAFP (Easier to Ask Forgiveness than Permission) -- 先嘗試再處理異常
10def get_value_eafp(data: dict, key: str) -> str | None:
11    try:
12        value = data[key]
13        if not isinstance(value, str):
14            return None
15        return value
16    except KeyError:
17        return None