refactor-method-complexity-reduce

重構方法以降低認知複雜度

目標

重構方法 ${input:methodName}，透過將邏輯提取到專注的輔助方法中，將其認知複雜度降低至 ${input:complexityThreshold} 或以下。

指示

1. 分析當前方法，找出認知複雜度的來源：

   • 巢狀條件陳述式
   • 多個 if-else 或 switch 鏈
   • 重複的程式碼區塊
   • 包含條件的多個迴圈
   • 複雜的布林運算式

2. 識別提取機會：

   • 可提取到獨立方法中的驗證邏輯
   • 重複出現的類型特定或情況特定處理
   • 複雜的轉換或計算
   • 多次出現的常見模式

3. 提取專注的輔助方法：

   • 每個輔助方法應有單一且明確的職責
   • 將驗證提取到獨立的 Validate* 方法中
   • 將類型特定邏輯提取到處理方法中
   • 為常見操作建立工具方法
   • 使用適當的存取層級（static、private、async）

4. 簡化主方法：

   • 減少巢狀深度
   • 用較小的協調呼叫取代大量的 if-else 鏈
   • 在適當情況下使用 switch 陳述式以獲得更清晰的分派
   • 確保主方法讀起來像高層次的流程

5. 保留功能：

   • 維持相同的輸入/輸出行為
   • 保留所有驗證和錯誤處理
   • 保留例外類型和錯誤訊息
   • 確保所有參數正確傳遞給輔助方法

6. 最佳實踐：

   • 當輔助方法不需要實例狀態時，將其設為 static
   • 及早使用 null 檢查和防護子句
   • 避免建立不必要的區域變數
   • 考慮使用元組處理多個回傳值
   • 將相關的輔助方法分組在一起

實作方法

• 在重構主流程之前先提取輔助方法
• 逐步測試以確保沒有回歸
• 使用有意義的名稱描述提取的職責
• 將提取的方法保留在靠近使用處
• 考慮將重複的程式碼模式轉換為通用方法

結果

重構後的方法應：

• 將認知複雜度降低至目標門檻 ${input:complexityThreshold} 或以下
• 更具可讀性和可維護性
• 有清晰的關注點分離
• 更容易測試和除錯
• 保留所有原始功能

測試與驗證

關鍵：完成重構後，你必須：

1. 執行所有現有測試，與重構的方法及其周圍功能相關
2. 強制：明確驗證測試結果顯示 "failed=0"
   • 絕不要假設測試通過 - 始終檢查實際測試輸出
   • 搜尋包含通過/失敗計數的摘要行（例如 "passed=X failed=Y"）
   • 如果摘要顯示任何非 "failed=0" 的數字，則測試失敗
   • 如果測試輸出在檔案中，請讀取整個檔案以定位並驗證失敗計數
   • 執行測試不等於驗證測試通過
   • 在明確確認零失敗之前，不要繼續
3. 如果任何測試失敗（failed > 0）：
   • 清楚說明有多少測試失敗
   • 分析每個失敗以了解哪些功能被破壞
   • 常見原因：null 處理、空集合檢查、條件邏輯錯誤
   • 在重構的程式碼中找出根本原因
   • 修正重構的程式碼以恢復原始行為
   • 重新執行測試並驗證輸出中的 "failed=0"
   • 重複直到所有測試通過（failed=0）
4. 驗證編譯 - 確保沒有編譯錯誤
5. 檢查認知複雜度 - 確認指標在目標門檻 ${input:complexityThreshold} 或以下

確認清單

• [ ] 程式碼編譯無錯誤
• [ ] 測試結果明確顯示 "failed=0"（透過讀取輸出驗證）
• [ ] 所有測試失敗已分析並修正（如有發生）
• [ ] 認知複雜度在目標門檻 ${input:complexityThreshold} 或以下
• [ ] 所有原始功能已保留
• [ ] 程式碼遵循專案慣例與標準