這種討論clean code的東西
各有各的說詞
我個人也是偏向不註解
但可能註解說明該module功能
或是註解回傳的資料結構
譬如
def get_city_population():
"""
return ［
{Taipei:[
{NanGan:1000},{WanHua:1000}...］
]
...
]
"""
手機排版隨便排的看不懂請見諒
讓使用方法的人快速了解嵌套結構
當然這也有code與註解版本不相符的問題
不過個人覺得這會算是幫助快速理解
蠻實用的註解方式
而太基本的方法千萬不要多寫
特別是強型別的語言更別加廢話註解
public int getAge(User user)
這種註解取得user年齡的廢話
就是為了註解而註解了
程式碼能夠完整表達意圖時
只需要思考意圖之外
還需要告訴讀code的人的事
才需要額外說明
譬如
#Boss required to do this, you have to suck it
有時候去看一些大型專案的開源原始碼
註解比code還多啊XD
而且一些是在講繼承與依賴關係
個人覺得不是那麼必要
真正需要去搞懂原始碼的時候
通常自己靠源碼分析工具
來了解相依性的部分
還有圖可以看呢
總結來說註解的重點就是
能夠幫助讀者快速理解
以及程式碼之外的告知事項
其他就沒有必要
而註解的事項盡量會是不因為code的改動
而需要去修改的這類型註解
更新code忘記更新註解
每個人都一定有過這種經驗嘛