回答審查意見
透過在原始碼中插入解釋性註解來解決程式碼審查意見,記錄設計考量,讓未來的審查者不會再提出相同疑問。
輸入
兩個輸入皆從對話脈絡中推斷,僅在不明確時才詢問。
輸入 1 — 審查意見。
審查者的發現:通常是一個表格行,包含位置(檔案:行號)和問題描述。
該表格通常來自 dakubo-display-pr-remarks 或 dakubo-review-commit-range 技能。如果對話中沒有表格且其中一個技能可用,則使用該技能建立表格。如果沒有,則詢問使用者審查意見。
輸入 2 — 解釋說明。 開發者的回應:為什麼程式碼目前是正確的、背後的設計決策、接受的取捨,或是審查者遺漏的大局觀。這可能不直接反駁意見,而是改變審查者的觀點。
流程
- 讀取輸入 1 中指定位置的檔案。
- 確定意見所指的具體建構(方法、區塊、欄位、行)。
- 撰寫一個註解:
- 擷取輸入 2 的精髓(理由 / 決策 / 背景)。
- 簡潔 — 最多一到四行。
- 不提及審查者、PR 或意見編號(註解比審查更長久)。
- 不重複程式碼已經說明的內容 — 只補充從程式碼中看不出來的 WHY。
- 可選擇性地處理意見的疑慮,使解釋更清楚。
- 將註解放在目標建構的上方,或如果行內註解自然合適,則放在行內。
- 套用編輯。
輸出
確認新增註解的檔案和行號。一句話即可。
禁止事項
- 除非使用者明確要求,否則不要改寫程式碼。
- 不要撰寫僅重述程式碼功能的註解。
- 不要在註解內提及「審查者說…」或「PR #N」。
- 不要新增超過約四行的註解;如果解釋需要更多篇幅,應放在設計文件或提交訊息中,而非行內註解。