【軟技能】程式員的自我修養-代碼注釋

最近公司開始代碼review，使我對代碼注釋有了更深層次的了解。

1. 注釋首先要告訴維護的人這段代碼是誰寫的。
2. 函數頭注釋應該描述函數調用的前置條件和後置條件。
3. 注釋不是描述代碼做了什麼而是描述為什麼這麼做。好的代碼注釋應該告訴後來人維護的思路。

作者在寫代碼時已經考慮了後續版本的需求哪裡可能會變化，變化後隻要怎麼修改一下哪裡的代碼就可以支援。這樣的代碼注釋看起來很舒心，作者是有思想的，也是負責任的。

當然，對于業務邏輯實在太複雜的部分。看代碼不能一下就看出個是以然來，通過一段文字說明，把關鍵點點出來，還是很有好處的。

1. 注釋描述的内容應該和代碼是一緻的

修改代碼時未同步修改注釋，注釋成了誤導。錯誤的注釋比沒有注釋更糟糕。

1. 取一個有意義的函數名，讓它自注釋。

開發過程中經常看到這樣的情況：某個功能要處理A，B，C三件事，拆分成三個函數，函數名就是DoA, DoB, DoC。隻能說太随意了，還可以再斟酌一下，更具體一點。

1. 取一個好的變量名，讓人不易誤用。