代碼重構：注釋（Comments）

什么是注釋的壞味道（Comments）

定義:

1.某段代碼有大段的注釋，這些注釋之所以存在是因為代碼很糟糕

2.代碼注釋錯誤，或者缺少必要的注釋[1]

影響: 以注釋掩蓋了代碼壞味道，或者沒有正確的注釋，不便閱讀。影響了代碼的可讀、可維護性

改進目標: 消除不必要的注釋，補充必要的注釋，提升代碼可讀可維護性

方法

1.提取變量（代碼段注釋）

2.提取方法（代碼段注釋）

3.方法/變量改名（方法/變量注釋）

4.補充/修改必要的注釋[2]

注：[1] [2]《重構》一書中并無此條，但業務代碼中確實存在缺少必要注釋、注釋錯誤等情況，比如Javadoc、算法注釋等，因此專門列出

案例1：通過注釋隱藏壞味道

問題

試圖通過注釋來解釋不易理解的代碼

案例1：改進目標

重構目標

抽取變量、方法，并用合理的命名，實現代碼的自注釋

修改方案

提取變量：代碼段的注釋

提取方法：代碼段的注釋

方法/變量改名：方法/變量的注釋

案例2：業務代碼中其他一些常見注釋問題

癥狀/問題

1.缺少必要的注釋，包括缺少Javadoc或空有格式，算法代碼缺少注釋等

2.注釋錯誤，注釋與方法、參數、功能等不匹配

重構目標

補充或修改注釋

思考：要有效注釋，但不建議消除注釋

實際問題：不是注釋多了，而是注釋少了，有效注釋更少

缺乏有效的說明和注釋

注釋與代碼實現不一致

為了注釋而注釋的冗余

晦澀難懂的低質量注釋

有效日志：個人可追求代碼即文檔，但現階段還是應該重視而不是消除注釋

代碼的基本功能描述

代碼使用的前提和限制條件等

代碼實現的特殊考慮和算法等

其他必要的代碼說明

規范及工具

總結

注釋本身非壞味道，只是不合理的使用注釋，會隱藏代碼潛在的問題，掩蓋了代碼的壞味道

[1]《重構》一書中并沒有這一條，但實際代碼中經常會存在缺少必要注釋、注釋錯誤等情況，比如Javadoc、算法注釋等，因此專門列出

[2]同[1]

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。