介紹你一個小知識吧(說是小知識,不過關系重大)
就是如何寫注釋.以往我一直都比較困惑注釋到底要寫些什麼,經常注釋了很多,可是回頭看的時候卻發現注釋一點信息量也沒有
一般我們所說的注釋都是針對函數(也就是方法),因為函數是模塊化設計的最小單元(類還不算最小單元)
一個函數意味著一個功能,所以,函數的注釋至少要有兩條:
1.這個函數在什麼情況下可以得到正確的運行結果,比如開平方的函數,參數不能為負數.
這個叫做'前導條件',建議在方法的開頭注明,像這樣 :
void xxx() {
//pre : 前導條件
}
不是所有的函數都具有前導,有的函數可以在任何情況下得到正確結果,比如加法之類的.
所以,有時候,前導條件可以省略不寫
2.這個函數執行之後會造成什麼影響.比如設置對象的某個狀態或者返回某一個值.
這個叫做'後置條件',建議在方法的結尾注明,像這樣 :
void xxx() {
....
//post : 後置條件
}
所有的函數都具有後置條件.因為一個函數被調用之後肯定會造成影響,否則這個函數就沒有存在地意義.
一定要寫明每一個函數的後置條件.
3.函數當中假如用到了公式或者定理,要在注釋當中用了那條定理或者公式,最好能付上公式或者定理的簡要說明.(當然,假如是勾股定理這種簡單的,不說也可以)
4.假如某一段代碼是順序不能顛倒的,要注明,像這樣:
...;
#隔一行
//處理XXX
//sequence dependent
//1st : xxx
....;
//2nd : xxx
...;
//3rd : xxx
...;
#隔一行
.....
注重了這幾點,應該就不會再碰到不知道該注釋什麼,或者注釋中盡是廢話(我經常這樣) 的問題了.
注重 : 在寫代碼的時候寫的注釋才有價值,假如在代碼已經寫完才來補注釋,那麼就不要再補了,把要寫的寫進文檔就可以.
注釋要求記錄程序員寫程序時候的思維過程
這裡提到的只是我個人的編碼習慣,主要是介紹一下寫注釋需要注重的一些細節.
