Clean Code 無瑕的程式碼 第4章 註解

       第四章內容談到註解，作者提到一個重要觀念註解不是越多越好，可以透過變數名稱、類別名稱或函數名稱表達程式碼的用途，可以少寫很多註解。軟體版本控管軟體也可以消滅大量多餘無意義的註解。

寫註解不是好事，會要寫註解表示程式碼表達能力不足。

程式會一直修改，經常會發生程式改了註解沒有跟著修改的情況，導致註解與程式碼不一致，假註解比沒有註解還要更可怕。

最好的方法是程式碼就能寫清楚，不用再寫註解。

註解無法彌補糟糕的程式碼

花時間寫註解，不如花時間整理程式。

用程式碼表達你的本意

從範例可看出可以用「物件名稱」或「函數名稱」取代註解。

有益的註解

有時候還是必須寫有益的註解

法律型的註解

法律資訊相關的註解。

資訊型註解

寫出函數的意圖，或是回傳值的格式。

可以修改函數名稱或是新增特別類別取代註解。

對意圖的解釋

寫出這段程式想要做什麼。

闡明

把難解的參數或回傳值翻譯成具有可讀性的文字。要注意註解的正確性。

對於後果的告誡

警告訊息，警告其他程式設計師會有什麼後果。

TODO (待辦事項) 註解

還沒有完成的事項，注意事項。

定期審查TODO，並且刪除不再需要的待辦事項。

放大重要性

說明程式碼的重要性。

公共 API 裡面的 Javadoc

Javadoc 描寫公共 API 的使用方法。

糟糕的註解

喃喃自語

自言自語無意義的註解。

多餘的註解

與程式無關的註解。

誤導型註解

讓讀者容易誤解的註解。

規定型註解

可以不寫註解，卻被規定要寫註解。

日誌型註解

每次更新內容寫成註解。作者認為現在有軟體版本控管軟體，可以移除日誌型註解。

干擾型註解

等同多餘的註解。

可怕的干擾

同樣是多餘的註解。

當你可以使用函式或變數時就別使用註解

函式名稱與變數名稱就可以表達程式，就可以不添加註解。

位置的標誌物

有的工程師會用註解畫圖作為標記。

右大括號後面的註解

參考4-6，如果出現巢狀的情況才有意義，作者認為還是要追求函數簡短，就可以不用寫右大括號後面的註解。

出處及署名

寫程式的人有可能用自己的名子作為註解。有軟體控管軟體之後可以不需要這種註解。

被註解起來的程式碼

這種程式碼後患無窮，以後接手的工程師會不敢刪除這段註解。

有軟體控管軟體之後可以大膽刪除這類型的註解。

HTML 形式的註解

HTML 太複雜，不應該成為註解。

非區域性的資訊

其他地方的註解，與本區程式碼不相關的註解。

過多的資訊

多餘的註解。

不顯著的關連

寫得不清不楚的註解。

函式的標頭

函式名稱可以取代函式標頭註解。

非公共程式碼裡的 Javadoc

Javadoc 對於了解公共API有幫助，自己寫的程式若不想成為公共API，又要模仿Javadoc ，只會產生一堆垃圾。

範例

4-8是4-7重構後的版本。

4-8有兩個註解，第一個註解幫助讀者了解演算法，第二個註解解釋迴圈終止的條件。