Comments(過多的注釋)

官方解釋:

別擔心,我們並不是說你不該寫注釋。從嗅覺上說,Comments不是一種壞味道;事實上它們還是一種香味呢。我們之所以要在這裡提到Comments,因為人們常把它當作除臭劑來使用。常常會有這樣的情況:你看到一段代碼有着長長的注釋,然後發現,這些注釋之所以存在乃是因為代碼很糟糕。這種情況的發生次數之多,實 在令人吃驚。

Comments可以帶我們找到本章先前提到的各種壞味道。找到壞味道後,我們首先應該以各種重構手法把壞味道去除。完成之後我們常常會發現:注釋已經變得多餘了,因為代碼已經清楚說明了一切。

如果你需要注釋來解釋一塊代碼做了什麼,試試 Extract Method;如果method已經提煉出來,但還是需要注釋來解釋其行為,試試Rename Method;如果你需要注釋說明某些系統的需求規格,試試 Introduce Assertion。

TIP:當你感覺需要撰寫注釋,請先嘗試重構,試着讓所有注釋都變得多餘。

如果你不知道該做什麼,這才是注釋的良好運用時機。除了用來記述將來的打算之外,注釋還可以用來標記你並無十足把握的區域。你可以在注釋里寫下自己「為什 么做某某事」。這類信息可以幫助將來的修改者,尤其是那些健忘的傢伙。