改善與重構程式碼
使用 Verdent 進行程式碼改善與重構的最佳實踐
Verdent for VS Code 協助你在多個檔案間安全地重構與改善程式碼，同時保留原有功能。透過搭配 Explorer 子代理的 Plan Mode，你可以在進行任何變更前找出所有受影響的檔案，確保重構全面而不遺漏任何實例。
你將學到什麼
- 提出聚焦於成果而非實作方式的有效重構請求
- 透過依賴管理在多個檔案間安全重構
- 請求程式碼品質改善與最佳化建議
- 以多階段方式處理大規模重構專案
- 透過演算法與架構改善來最佳化效能
- 在重構操作期間保留程式碼功能
先決條件
在使用 Verdent 重構前：
- 已安裝 Verdent 擴充功能的 Visual Studio Code
- 在 VS Code 中開啟一個程式碼庫或專案工作區
- 有可用點數的有效 Verdent 訂閱方案
- 建議使用版本控制（Git），以便在需要時安全回復
提出有效的重構請求
描述你想改善什麼以及為什麼，而非該如何修正。讓 Verdent 分析程式碼，並根據你的專案模式提出最佳方案。
有效的重構請求：
聚焦於你想要的成果，而非實作方式：
Refactor the UserController to improve readability and reduce duplicationThis authentication logic is scattered across multiple files. Consolidate it into a single moduleImprove error handling in the API layer to be more consistent and informativeVerdent 會分析程式碼、找出所有受影響的檔案、檢視模式，並提出符合你程式碼庫慣例的具體重構策略。
最佳實踐：使用 Plan Mode
在 Plan Mode 中開始重構請求。Verdent 將會：
- 分析程式碼並找出所有受影響的檔案
- 在進行任何變更前提出詳細的重構計畫
- 針對實作偏好詢問釐清問題
- 確切顯示將變更什麼以及變更順序
- 讓你檢視並調整方案
Plan Mode 範例：
In Plan Mode: Refactor authentication logic to use a centralized authentication utilityVerdent 將會：
- 使用 Explorer 找出所有驗證程式碼的位置
- 識別模式與不一致之處
- 提出統一的驗證介面
- 顯示哪些檔案會被修改
- 解釋重構順序
你可以請求 Verdent 將計畫儲存到 plan.md 檔案，以便在執行前進行額外檢視與團隊討論。
使用 Explorer 進行全面搜尋：
對於複雜的重構，明確要求 Verdent 使用 Explorer 代理進行徹底搜尋：
Use the Explorer agent to find all places where we manually validate email addresses, then refactor them to use a centralized validation utility這能確保 Verdent 找出每一個需要更新的位置，避免在程式碼庫中產生不一致的重構。
Plan Mode 對重構至關重要。它在執行前確切顯示將變更什麼，避免意外，並讓你能根據架構考量調整方案。
多檔案重構
Verdent 在多個檔案間進行重構，同時維護匯入、依賴關係與跨檔案引用。它會找出所有受影響的檔案、以正確順序更新它們，並確保整個程式碼庫的一致性。
多檔案重構的運作方式：
- 探索階段：Verdent（使用 Explorer）找出所有需要變更的檔案
- 依賴分析：識別檔案之間的依賴關係以決定更新順序
- 計畫建立：顯示所有將被修改的檔案以及變更順序
- 依序更新：依依賴順序修改檔案（例如：在使用型別的元件之前先修改型別）
- 匯入管理：自動更新匯入、匯出與跨檔案引用
- 驗證：檢查變更在所有檔案間是否一致
多檔案重構透過自動化依賴追蹤來保留功能，Verdent 會以原子方式更新所有受影響的檔案。
範例：
Rename the User interface to UserProfile across the entire projectVerdent 將會：
- 找出所有匯入或使用
User的檔案 - 識別型別定義、實作與使用之處
- 先更新型別定義，再更新實作，最後更新使用之處
- 調整所有匯入陳述式
- 確保整個程式碼庫的一致性
使用 Plan Mode 檢視範圍：
在執行多檔案重構前，於 Plan Mode 中檢視完整範圍：
In Plan Mode: Extract the authentication logic from UserController into a separate AuthServiceVerdent 將會顯示：
- 將建立哪些檔案（新的 AuthService）
- 將修改哪些檔案（UserController 與所有匯入者）
- 哪些程式碼會從 UserController 移到 AuthService
- 匯入與依賴關係將如何更新
這能避免意外的範圍蔓延，並確保你在繼續前理解完整的影響。
請求程式碼品質改善
Verdent 不會在未被要求的情況下主動建議改善。不過，你可以隨時請求程式碼品質審查與改善建議。
請求廣泛的程式碼品質審查：
Review this code for potential improvementsSuggest ways to improve code quality in the UserService moduleAre there any performance optimizations we could make here?Analyze the PaymentController for maintainability issuesVerdent 會分析程式碼並針對以下面向提供具體建議：
- 可讀性：變數命名、函式拆解、註解清晰度
- 效能：演算法複雜度、冗餘操作、快取機會
- 可維護性：程式碼重複、耦合、關注點分離
- 最佳實踐：設計模式、錯誤處理、測試覆蓋率
- 安全性：輸入驗證、驗證檢查、資料外洩
若需針對性的回饋，可引用特定檔案：
@services/UserService.js Review this module for dependency injection improvements@controllers/PaymentController.js Identify opportunities to reduce complexityVerdent 會在你專案模式的脈絡下檢視指定的程式碼，並提供可行的建議。
大規模重構專案
對於大規模重構，請使用 Plan Mode 搭配多階段方法以獲得最可靠的結果。Verdent 會將重構拆解為可管理的階段，讓你在繼續前檢視並核准每個階段。
多階段重構工作流程：
階段 1：初步分析
使用 Plan Mode 搭配 Explorer 代理，找出所有受影響的檔案與依賴關係：
In Plan Mode: Use Explorer to analyze our codebase and create a plan to replace our custom authentication with OAuth 2.0Verdent 會執行全面分析：
- 識別所有與驗證相關的程式碼
- 對應依賴關係與整合點
- 評估複雜度與風險區域
- 提出階段拆解方案
階段 2：階段規劃
Verdent 建立多階段計畫供檢視：
範例計畫：
- 階段 1：加入 OAuth 函式庫並設定端點
- 階段 2：更新使用者模型與資料庫結構
- 階段 3：遷移現有的驗證邏輯
- 階段 4：移除已棄用的驗證程式碼
- 階段 5：更新測試與文件
每個階段包含：
- 將被修改的檔案
- 預估複雜度
- 對前一階段的依賴
- 風險評估
階段 3：逐階段執行
一次執行一個階段，並在階段之間進行測試：
- 在 Plan Mode 核准階段 1
- 切換到 Agent Mode 並執行
- 徹底測試以驗證階段 1 運作正常
- 回到 Plan Mode 處理階段 2
- 重複直到所有階段完成
階段 4：迭代調整
在每個階段後檢視結果。若出現問題：
- 調整剩餘階段的計畫
- 視需要加入修正階段
- 根據發現調整方案
這種分階段方法確保安全性，並在大型重構專案出現問題時允許修正方向。
大規模重構應始終搭配版本控制進行。在每個階段後提交，這樣若出現問題即可回復而不會失去所有進度。
效能最佳化
Verdent 會分析程式碼以找出效能瓶頸，並建議最佳化方式，包括改善演算法複雜度、使用高效的資料結構，以及降低資源使用。
改善演算法複雜度：
Analyze the performance of this data processing function and suggest improvementsCan we improve the time complexity of this search algorithm?Verdent 會識別什麼：
- 演算法複雜度：O(n²) 迴圈、巢狀迭代、低效搜尋
- 冗餘計算：重複計算、不必要的操作
- 記憶體問題：記憶體洩漏、過度配置、大型物件保留
範例：
Optimize the searchProducts function that's currently O(n²)Verdent 會分析函式、找出低效之處（巢狀迴圈或重複的線性搜尋），並提出具體改善：
- 以雜湊表取代巢狀迴圈，實現 O(n) 查找
- 排序後使用二分搜尋，達到 O(log n) 複雜度
- 快取計算結果以避免冗餘計算
- 對昂貴操作實作記憶化
回應包含：
- 當前複雜度：說明為何目前程式碼較慢
- 建議方案：具體的演算法或資料結構變更
- 效能提升：預估改善幅度（例如 O(n²) → O(n log n)）
- 取捨：記憶體使用、程式碼複雜度、可維護性等考量
最佳化 UI 元件與渲染：
Optimize this component to reduce unnecessary re-rendersVerdent 會識別什麼：
- 前端效能：不必要的重新渲染、過大的套件體積、阻塞操作
- 元件生命週期：低效的 useEffect 依賴、缺少記憶化
- 狀態管理：冗餘的狀態更新、prop drilling
Verdent 會分析你的元件並建議最佳化方式，例如 React.memo、useMemo、useCallback 或元件拆分。
找出並修正 API 與資料庫瓶頸：
Identify performance bottlenecks in the API request handlerVerdent 會識別什麼：
- 資料庫效能：N+1 查詢、缺少索引、低效的 join
- API 效能：緩慢的端點、低效的資料抓取、缺少快取
Verdent 會檢視查詢模式，建議資料庫索引、快取策略與 API 最佳化技巧。
進行效能最佳化時，請提供典型資料量與效能限制的脈絡。這能協助 Verdent 提出適合你規模的方案（例如 100 筆 vs 100 萬筆）。
最佳化前先進行剖析，測量效能影響以確保最佳化帶來有意義的改善。
重構期間保留功能
Verdent 致力於在重構期間保留程式碼功能，維持相同的輸入、輸出與行為，同時改善內部實作。
Verdent 如何保留功能：
- 輸入/輸出分析：識別函式簽章、API 契約與預期行為
- 測試感知：將現有測試視為行為規格
- 保守變更：以最少的變更達成重構目標
- 驗證：可產生或執行測試以驗證功能是否被保留
安全重構的最佳實踐：
-
務必測試重構後的程式碼 - 即使有 Verdent 的分析，手動或自動化測試仍能驗證功能是否被保留，對複雜重構尤其重要
-
使用版本控制 - 在重構前提交，以便在出現問題時回復
-
漸進式重構 - 將大型重構拆解為較小的步驟，並在每次變更後測試
-
仔細檢視變更 - 檢視 diff 以理解變更了什麼以及原因
-
複雜重構使用 Plan Mode - 在執行前檢視方案以發現潛在問題
範例：安全重構請求
Refactor the calculateOrderTotal function to use a more maintainable structure, but ensure it produces identical results for all input casesVerdent 將會：
- 分析當前實作與邊界情況
- 提出重構後的結構
- 解釋為何重構後的版本是等效的
- 建議測試案例以驗證等效性
何時功能可能會改變：
在某些情況下，重構會刻意改變行為（修正錯誤、改善驗證）。請明確說明這一點：
Refactor the email validation function to correctly handle international domains, which the current implementation doesn't support這代表行為變更是預期且刻意的。
最佳實踐
描述問題，而非解法
讓 Verdent 分析程式碼並提出最佳重構方案，而非規定具體變更。
重構時務必使用 Plan Mode
在執行前檢視完整計畫。這能避免意外，並讓你能根據架構考量調整方案。
明確使用 Explorer 進行全面搜尋
若要徹底重構，請要求 Verdent 使用 Explorer 找出所有實例：「使用 Explorer 找出所有手動錯誤處理，然後重構為使用我們的錯誤工具。」
將大型重構拆解為階段
搭配階段間測試的多階段方法，比一次性完成所有事項更安全且更易管理。
在階段之間進行測試
在繼續下一階段前驗證每個階段運作正常。這能隔離問題並避免問題累積。
頻繁提交
使用版本控制在每個階段或重大變更後建立檢查點。這能在不失去所有進度的情況下安全回復。
儲存計畫供團隊檢視
對於重大重構，請求 Verdent 將計畫儲存到 plan.md，以便在執行前進行團隊討論。
為最佳化提供脈絡
請求效能改善時，請納入資料量、效能限制與可接受取捨的相關資訊。