1# 高認知負擔的程式碼
2def process(d):
3    r = []
4    for i in d:
5        if i[0] > 0 and i[1] != "" and len(i) >= 3:
6            t = i[0] * 2 + len(i[1])
7            if t > 10:
8                r.append((i[2], t))
9    return sorted(r, key=lambda x: x[1], reverse=True)

1Clean Code 的真正目標是：讓程式碼能被人類輕鬆理解

 1# 高認知負擔：需要記住 data 經歷了什麼轉換
 2data = get_raw_data()
 3data = filter_invalid(data)
 4data = normalize(data)
 5data = enrich(data)
 6result = aggregate(data)
 7
 8# 低認知負擔：每步都有清晰的命名
 9raw_data = get_raw_data()
10valid_data = filter_invalid(raw_data)
11normalized_data = normalize(valid_data)
12enriched_data = enrich(normalized_data)
13result = aggregate(enriched_data)

 1# 高認知負擔：temp 到底是什麼？
 2temp = user_input.strip()
 3temp = temp.lower()
 4temp = temp.replace(" ", "_")
 5temp = re.sub(r'[^a-z_]', '', temp)
 6
 7# 低認知負擔：每個變數都說明自己是什麼
 8trimmed_input = user_input.strip()
 9lowercase_input = trimmed_input.lower()
10underscored_input = lowercase_input.replace(" ", "_")
11clean_identifier = re.sub(r'[^a-z_]', '', underscored_input)

 1# 高認知負擔：process() 會修改什麼？
 2class DataProcessor:
 3    def process(self):
 4        self._validate()      # 可能修改 self.errors?
 5        self._transform()     # 可能修改 self.data?
 6        self._save()          # 可能修改 self.saved?
 7
 8# 低認知負擔：回傳值明確說明結果
 9class DataProcessor:
10    def process(self) -> ProcessResult:
11        errors = self._validate(self.data)
12        if errors:
13            return ProcessResult(success=False, errors=errors)
14
15        transformed = self._transform(self.data)
16        save_result = self._save(transformed)
17        return ProcessResult(success=True, saved_path=save_result)

1# 高認知負擔：需要跳到 MAGIC_VALUE 的定義
2if score > MAGIC_VALUE:
3    return "pass"
4
5# 低認知負擔：直接說明意圖
6PASSING_SCORE_THRESHOLD = 60
7if score > PASSING_SCORE_THRESHOLD:
8    return "pass"

 1# 不好：需要記住 user 是什麼
 2def process(user):
 3    if user[0] and user[1] > 18:
 4        return user[2]
 5
 6# 好：當下就能理解
 7def get_adult_user_name(user: User) -> Optional[str]:
 8    if user.is_active and user.age > 18:
 9        return user.name
10    return None

1# 不好：需要註解才能理解
2# 檢查用戶是否有權限
3if u.r >= 3 and u.s == 'a':
4    pass
5
6# 好：程式碼本身就是說明
7if user.role_level >= ADMIN_LEVEL and user.status == UserStatus.ACTIVE:
8    pass

 1# 不好：get 通常不應該修改狀態
 2def get_user_count(self):
 3    self._refresh_cache()  # 意外的副作用！
 4    return len(self._users)
 5
 6# 好：get 只做讀取
 7def get_user_count(self) -> int:
 8    return len(self._users)
 9
10def refresh_and_get_user_count(self) -> int:
11    self._refresh_cache()
12    return len(self._users)

 1def check_hook(path):
 2    with open(path) as f:
 3        c = f.read()
 4
 5    # 檢查 shebang
 6    if not c.startswith("#!"):
 7        return False, "no shebang"
 8
 9    # 解析配置
10    import yaml
11    cfg = yaml.safe_load(open(".claude/config.yaml"))
12
13    # 驗證
14    for h in cfg.get("hooks", []):
15        if h.get("path") == str(path):
16            if not os.path.exists(path):
17                return False, "not found"
18            if not os.access(path, os.X_OK):
19                return False, "not executable"
20            return True, "ok"
21
22    return False, "not registered"

 1from lib.config_loader import load_hook_config
 2from lib.hook_validator import validate_hook_file
 3
 4def check_hook(hook_path: Path) -> tuple[bool, str]:
 5    """
 6    檢查指定的 Hook 檔案是否有效。
 7
 8    Returns:
 9        (是否有效, 訊息)
10    """
11    # 載入配置
12    config = load_hook_config()
13
14    # 檢查是否已註冊
15    if not config.is_registered(hook_path):
16        return False, "Hook 未在配置中註冊"
17
18    # 驗證檔案
19    validation_result = validate_hook_file(hook_path)
20
21    return validation_result.is_valid, validation_result.message

1# 可以像故事一樣閱讀的程式碼
2user_submitted_form = receive_form_submission(request)
3validated_data = validate_form_data(user_submitted_form)
4save_to_database(validated_data)

1# 需要解謎的程式碼
2d = get(r)
3v = check(d)
4save(v)

1# 轉換敘事
2raw_input = read_user_input()
3cleaned_input = sanitize(raw_input)
4formatted_output = format_for_display(cleaned_input)

 1# 壞：過於簡短，無法理解
 2d = get_data()
 3t = time.time()
 4r = []
 5i = 0
 6
 7# 壞：過於通用，無法區分
 8data = get_user_data()
 9data2 = get_order_data()
10temp = process(data)
11result = combine(temp, data2)
12
13# 壞：誤導性的名稱
14user_list = get_user()  # 實際上回傳單一用戶，不是列表！

 1# 好：說明「這是什麼」
 2user_profile = get_user_profile(user_id)
 3current_timestamp = time.time()
 4validated_items = []
 5item_index = 0
 6
 7# 好：能區分不同用途
 8user_data = get_user_data()
 9order_data = get_order_data()
10merged_report = merge_user_and_orders(user_data, order_data)
11
12# 好：名稱和實際內容一致
13active_user = get_active_user()  # 單數名稱，回傳單一用戶
14active_users = get_active_users()  # 複數名稱，回傳列表

1# 不好：名稱說明來源
2config_from_yaml = load_config()
3user_after_validation = validate(user)
4
5# 好：名稱說明內容
6app_config = load_config()
7valid_user = validate(user)

1# 不好：不清楚是什麼意思
2user_status = True
3file_check = False
4
5# 好：讀起來像問句的答案
6is_user_active = True      # "Is user active?" - Yes
7has_valid_license = False  # "Has valid license?" - No
8can_edit_document = True   # "Can edit document?" - Yes
9should_retry = False       # "Should retry?" - No

1# 不好：不清楚是單一還是多個
2user = get_all_users()  # 回傳列表，但名稱是單數
3user_list = get_user()  # 回傳單一用戶，但名稱暗示列表
4
5# 好：名稱反映結構
6users = get_all_users()           # 複數 = 列表
7user = get_user(user_id)          # 單數 = 單一物件
8user_ids = get_all_user_ids()     # 複數 + 型別提示
9user_id_to_name = build_user_map()  # 說明映射關係

 1# 壞：動詞太模糊
 2def process(data):
 3    pass
 4
 5def handle(request):
 6    pass
 7
 8def do_something(item):
 9    pass
10
11def manage_users():
12    pass
13
14# 壞：不清楚會做什麼
15def user_operation(user, action):
16    pass
17
18def data_stuff(d):
19    pass

 1# 好：清楚說明動作和目標
 2def validate_user_input(user_input: str) -> ValidationResult:
 3    pass
 4
 5def extract_branch_name(git_output: str) -> str:
 6    pass
 7
 8def format_error_message(error: Exception) -> str:
 9    pass
10
11def calculate_total_price(items: list[OrderItem]) -> Decimal:
12    pass

 1# 不好：名稱洩漏實作細節
 2def loop_through_and_sum(numbers):
 3    pass
 4
 5def use_regex_to_find_emails(text):
 6    pass
 7
 8# 好：名稱說明意圖
 9def calculate_sum(numbers):
10    pass
11
12def extract_email_addresses(text):
13    pass

 1# 好：對稱的命名
 2def open_connection():
 3    pass
 4
 5def close_connection():
 6    pass
 7
 8# 好：對稱的命名
 9def start_processing():
10    pass
11
12def stop_processing():
13    pass
14
15# 不好：不對稱
16def open_connection():
17    pass
18
19def disconnect():  # 應該是 close_connection
20    pass

1# 高認知負擔版本
2d = fetch()
3d = clean(d)
4d = transform(d)
5r = aggregate(d)

1# 低認知負擔版本
2raw_data = fetch_user_data()
3cleaned_data = remove_invalid_entries(raw_data)
4normalized_data = normalize_formats(cleaned_data)
5report = generate_summary_report(normalized_data)

 1# 需要追溯 4 步
 2x = get_data()      # 第 1 步
 3x = process(x)      # 第 2 步
 4x = filter(x)       # 第 3 步
 5result = format(x)  # 第 4 步：x 到底是什麼？
 6
 7# 不需要追溯
 8raw_data = get_data()
 9processed_data = process(raw_data)
10filtered_data = filter(processed_data)
11formatted_output = format(filtered_data)  # 直接看名稱就知道是過濾後的資料

 1# 重構前（高認知負擔）
 2def check(p):
 3    c = open(p).read()
 4    if c.startswith("#!"):
 5        l = c.split("\n")
 6        if len(l) > 1:
 7            return l[1].startswith("# -*- coding")
 8    return False
 9
10# 重構後（低認知負擔）
11def has_valid_python_header(file_path: Path) -> bool:
12    """檢查 Python 檔案是否有有效的檔頭"""
13    file_content = file_path.read_text()
14
15    has_shebang = file_content.startswith("#!")
16    if not has_shebang:
17        return False
18
19    lines = file_content.split("\n")
20    has_encoding_declaration = (
21        len(lines) > 1 and
22        lines[1].startswith("# -*- coding")
23    )
24
25    return has_encoding_declaration

 1class ReportGenerator:
 2    def generate(self, report_type: str, data: dict) -> str:
 3        if report_type == "pdf":
 4            # 100 行 PDF 生成邏輯
 5            return self._generate_pdf(data)
 6        elif report_type == "excel":
 7            # 80 行 Excel 生成邏輯
 8            return self._generate_excel(data)
 9        elif report_type == "html":
10            # 60 行 HTML 生成邏輯
11            return self._generate_html(data)
12        else:
13            raise ValueError(f"Unknown report type: {report_type}")

 1from abc import ABC, abstractmethod
 2
 3class ReportFormatter(ABC):
 4    """報告格式化器的抽象介面"""
 5
 6    @abstractmethod
 7    def format(self, data: dict) -> str:
 8        """將資料格式化為報告"""
 9        pass
10
11class PdfFormatter(ReportFormatter):
12    def format(self, data: dict) -> str:
13        # PDF 生成邏輯
14        pass
15
16class ExcelFormatter(ReportFormatter):
17    def format(self, data: dict) -> str:
18        # Excel 生成邏輯
19        pass
20
21class HtmlFormatter(ReportFormatter):
22    def format(self, data: dict) -> str:
23        # HTML 生成邏輯
24        pass
25
26class ReportGenerator:
27    def __init__(self, formatter: ReportFormatter):
28        self._formatter = formatter
29
30    def generate(self, data: dict) -> str:
31        return self._formatter.format(data)

1class CsvFormatter(ReportFormatter):
2    def format(self, data: dict) -> str:
3        # CSV 生成邏輯
4        pass
5
6# 使用
7generator = ReportGenerator(CsvFormatter())
8report = generator.generate(data)

 1# 違反 SRP：一個類別做太多事
 2class UserManager:
 3    def create_user(self, data):
 4        # 驗證邏輯
 5        # 資料庫操作
 6        # 發送歡迎郵件
 7        # 記錄日誌
 8        pass
 9
10    def delete_user(self, user_id):
11        # 權限檢查
12        # 資料庫操作
13        # 清理關聯資料
14        # 發送通知
15        # 記錄日誌
16        pass

 1# 遵循 SRP：每個類別只做一件事
 2class UserValidator:
 3    def validate(self, data: dict) -> ValidationResult:
 4        pass
 5
 6class UserRepository:
 7    def create(self, user: User) -> User:
 8        pass
 9
10    def delete(self, user_id: str) -> bool:
11        pass
12
13class EmailService:
14    def send_welcome_email(self, user: User) -> None:
15        pass
16
17class UserService:
18    def __init__(
19        self,
20        validator: UserValidator,
21        repository: UserRepository,
22        email_service: EmailService
23    ):
24        self._validator = validator
25        self._repository = repository
26        self._email_service = email_service
27
28    def create_user(self, data: dict) -> User:
29        validation = self._validator.validate(data)
30        if not validation.is_valid:
31            raise ValidationError(validation.errors)
32
33        user = self._repository.create(User.from_dict(data))
34        self._email_service.send_welcome_email(user)
35        return user

 1# 難以命名 = 職責不單一
 2class UserStuffManager:  # "stuff" 說明不知道它具體做什麼
 3    pass
 4
 5class DataProcessorAndValidator:  # "and" 說明做了兩件事
 6    pass
 7
 8class HelperUtils:  # "helper/utils" 說明是雜項收集
 9    pass
10
11# 容易命名 = 職責單一
12class UserAuthenticator:  # 清楚：處理用戶認證
13    pass
14
15class ConfigurationLoader:  # 清楚：載入配置
16    pass
17
18class EmailFormatter:  # 清楚：格式化郵件
19    pass

 1# .claude/lib/config_loader.py
 2class ConfigLoader:
 3    """
 4    單一職責：載入和快取配置檔案
 5
 6    不負責：
 7    - 驗證配置內容
 8    - 使用配置執行操作
 9    - 修改配置
10    """
11
12    def __init__(self, config_path: Path):
13        self._config_path = config_path
14        self._cache: Optional[dict] = None
15
16    def load(self) -> dict:
17        """載入配置，使用快取避免重複讀取"""
18        if self._cache is None:
19            self._cache = self._read_config()
20        return self._cache
21
22    def _read_config(self) -> dict:
23        with open(self._config_path) as f:
24            return yaml.safe_load(f)

 1# .claude/lib/parsers/base.py
 2class LanguageParser(ABC):
 3    """語言解析器的抽象介面"""
 4
 5    @abstractmethod
 6    def parse(self, content: str) -> ParseResult:
 7        pass
 8
 9    @abstractmethod
10    def get_supported_extensions(self) -> list[str]:
11        pass
12
13# .claude/lib/parsers/python_parser.py
14class PythonParser(LanguageParser):
15    def parse(self, content: str) -> ParseResult:
16        # Python 解析邏輯
17        pass
18
19    def get_supported_extensions(self) -> list[str]:
20        return [".py"]
21
22# .claude/lib/parsers/factory.py
23class ParserFactory:
24    """
25    對擴展開放：新增語言只需實作 LanguageParser
26    對修改封閉：不需要修改此工廠類別
27    """
28
29    _parsers: dict[str, type[LanguageParser]] = {}
30
31    @classmethod
32    def register(cls, parser_class: type[LanguageParser]) -> None:
33        for ext in parser_class.get_supported_extensions():
34            cls._parsers[ext] = parser_class
35
36    @classmethod
37    def get_parser(cls, file_extension: str) -> LanguageParser:
38        parser_class = cls._parsers.get(file_extension)
39        if parser_class is None:
40            raise UnsupportedLanguageError(file_extension)
41        return parser_class()

 1# .claude/lib/parsers/dart_parser.py
 2class DartParser(LanguageParser):
 3    def parse(self, content: str) -> ParseResult:
 4        # Dart 解析邏輯
 5        pass
 6
 7    def get_supported_extensions(self) -> list[str]:
 8        return [".dart"]
 9
10# 註冊（可在初始化時自動完成）
11ParserFactory.register(DartParser)

 1# 自訂實作（看似合理，實則隱藏成本）
 2class LazyFileHandler(logging.FileHandler):
 3    """延遲建立檔案的 Handler"""
 4    def __init__(self, filename, mode='a', encoding=None):
 5        self.filename = filename
 6        self.mode = mode
 7        self._file_created = False
 8        # 不呼叫 super().__init__() 以避免建立檔案
 9        logging.Handler.__init__(self)
10
11    def emit(self, record):
12        if not self._file_created:
13            os.makedirs(os.path.dirname(self.filename), exist_ok=True)
14            self._file_created = True
15        super().emit(record)
16        # AttributeError: 'LazyFileHandler' has no attribute 'stream'

11. 開發成本：寫自訂類別          ~30 分鐘
22. 除錯成本：追蹤 AttributeError  ~1 小時
33. 修復成本：派發 hotfix 任務      ~2 小時
44. 驗證成本：確認修復後無迴歸      ~30 分鐘
5─────────────────────────────────
6   總成本：~4 小時

1# 一行解決
2handler = logging.FileHandler(filename, delay=True)
3# delay=True：延遲到第一次 emit 時才建立檔案
4# Python 3.0 就已存在，經過 15+ 年的穩定性驗證

1# 這段程式碼出現在 11 個 Hook 檔案中
2def read_json_from_stdin():
3    import sys, json
4    try:
5        return json.loads(sys.stdin.read())
6    except Exception:
7        return {}

 1# 修改後的版本
 2def read_json_from_stdin():
 3    import sys, json, logging
 4    logger = logging.getLogger(__name__)
 5    try:
 6        data = sys.stdin.read()
 7        return json.loads(data)
 8    except json.JSONDecodeError as e:
 9        logger.warning("stdin JSON 解析失敗: %s", e)
10        return {}
11    except Exception as e:
12        logger.error("stdin 讀取異常: %s", e)
13        return {}

1第 1 次修改：11 處 x 5 分鐘 = 55 分鐘
2第 2 次修改：11 處 x 5 分鐘 + 排查第 1 次遺漏的 bug = 75 分鐘
3第 3 次修改：11 處 x 5 分鐘 + 排查前兩次的行為不一致 = 120 分鐘
4...

 1# lib/hook_io.py（共用模組）
 2def read_json_from_stdin() -> dict:
 3    """
 4    從 stdin 讀取 JSON 資料。
 5
 6    Returns:
 7        解析後的字典，失敗時返回空字典
 8    """
 9    import sys, json, logging
10    logger = logging.getLogger(__name__)
11    try:
12        data = sys.stdin.read()
13        return json.loads(data)
14    except json.JSONDecodeError as e:
15        logger.warning("stdin JSON 解析失敗: %s", e)
16        return {}
17    except Exception as e:
18        logger.error("stdin 讀取異常: %s", e)
19        return {}

1# 每個 Hook 檔案中
2from lib.hook_io import read_json_from_stdin
3
4input_data = read_json_from_stdin()

1# 「安全」的錯誤處理（實際上是最危險的）
2def run_hook_safely(hook_func):
3    try:
4        hook_func()
5    except Exception as e:
6        # 只寫入檔案日誌，不通知任何人
7        log_to_file(f"Hook 失敗: {e}")

11. 發現問題            0 分鐘（偶然發現，否則可能更久）
22. 確認哪些 Hook 失敗    30 分鐘（需要手動逐一檢查）
33. 找到失敗原因          2 小時（沒有日誌可看，只能猜測）
44. 修復失敗的 Hook       1 小時
55. 驗證修復效果          30 分鐘
66. 確認沒有其他受影響的部分  1 小時
7─────────────────────────
8   總成本：~5 小時（且可能仍有遺漏）

1def run_hook_safely(hook_func, hook_name: str):
2    try:
3        hook_func()
4    except Exception as e:
5        # 寫入檔案日誌（完整追蹤）
6        log_to_file(f"Hook 失敗: {e}", traceback=True)
7        # 輸出到 stderr（確保使用者可見）
8        print(f"[Hook Error] {hook_name}: {e}", file=sys.stderr)

11. 發現問題           0 分鐘（stderr 立即可見）
22. 確認失敗原因        5 分鐘（日誌有完整的 traceback）
33. 修復失敗的 Hook     30 分鐘
44. 驗證修復效果        10 分鐘
5─────────────────────────
6   總成本：~45 分鐘

 1# 方案 A：每次都清理
 2def run_hook():
 3    execute_hook_logic()
 4    cleanup_old_logs()  # 每次 Hook 執行後都清理
 5
 6# 方案 B：每 N 次清理一次
 7LOG_CLEANUP_TRIGGER_FREQUENCY = 10
 8
 9def run_hook():
10    execute_hook_logic()
11    state["execution_count"] += 1
12    if state["execution_count"] % LOG_CLEANUP_TRIGGER_FREQUENCY == 0:
13        cleanup_old_logs()
14
15# 方案 C：外部排程清理
16# 由 cron job 或系統排程器負責
17# Hook 本身不做任何清理

 1LOG_CLEANUP_TRIGGER_FREQUENCY = 10
 2
 3def maybe_cleanup_logs(execution_count: int, log_dir: Path) -> None:
 4    """
 5    根據執行次數決定是否清理舊日誌。
 6
 7    每 LOG_CLEANUP_TRIGGER_FREQUENCY 次觸發一次清理，
 8    在精確度和 I/O 成本之間取得平衡。
 9    """
10    if execution_count % LOG_CLEANUP_TRIGGER_FREQUENCY != 0:
11        return
12    cleanup_old_logs(log_dir)

 1# 方案 A：直接執行，失敗再處理
 2def dispatch_task(task):
 3    try:
 4        result = execute(task)  # 消耗資源
 5    except PermissionError:
 6        # 失敗了，資源已經浪費
 7        log("任務失敗：權限不足")
 8        return None
 9
10# 方案 B：預先驗證
11def dispatch_task(task):
12    if not has_required_permissions(task):
13        log("跳過：權限不足")
14        return None
15    result = execute(task)  # 確認可行才消耗資源

1預驗證成本 = 驗證時間 x 每次派發
2失敗成本 = 任務執行時間 x 失敗機率
3
4當 失敗成本 > 預驗證成本 時，預驗證是值得的

1總成本 = 開發成本 + 維護成本 + 修復成本 + 機會成本