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

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

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

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

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

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

用程式碼表達你的本意

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

有益的註解

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

法律型的註解

法律資訊相關(guān)的註解。

資訊型註解

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

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

對意圖的解釋

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

闡明

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

對於後果的告誡

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

TODO (待辦事項) 註解

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

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

放大重要性

說明程式碼的重要性。

公共 API 裡面的 Javadoc

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

糟糕的註解

喃喃自語

自言自語無意義的註解。

多餘的註解

與程式無關(guān)的註解。

誤導型註解

讓讀者容易誤解的註解。

規(guī)定型註解

可以不寫註解，卻被規(guī)定要寫註解。

日誌型註解

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

干擾型註解

等同多餘的註解。

可怕的干擾

同樣是多餘的註解。

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

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

位置的標誌物

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

右大括號後面的註解

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

出處及署名

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

被註解起來的程式碼

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

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

HTML 形式的註解

HTML 太複雜，不應(yīng)該成為註解。

非區(qū)域性的資訊

其他地方的註解，與本區(qū)程式碼不相關(guān)的註解。

過多的資訊

多餘的註解。

不顯著的關(guān)連

寫得不清不楚的註解。

函式的標頭

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

非公共程式碼裡的 Javadoc

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

範例

4-8是4-7重構(gòu)後的版本。

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