Re: [請益] 寫註解到底是不是好習慣

[ripple0129 (perry tsai)]

這種討論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忘記更新註解
每個人都一定有過這種經驗嘛

--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 1.171.204.87
※ 文章網址: https://www.ptt.cc/bbs/Soft_Job/M.1545925856.A.7C1.html
→ testPtt: 我是會做相依性註解 程式改這種註解難免要改
推 piadora: 請問有什麼工具可以幫助畫圖
譬如說
VS的Code maps
PHP RIPS
※ 編輯: ripple0129 (1.171.204.87), 12/28/2018 01:06:36
推 BoXeX: 我是覺得跟開發環境和團隊狀況有關
→ BoXeX: 當整個團隊能用的工具越少  就越需要註解來幫忙
→ BoXeX: 還有如果要給其他團隊看的  多一點註解可以幫助理解
→ BoXeX: 同team的人習慣接近了   覺得clean到不行
→ BoXeX: 換個團隊看就變成無字天書
推 h124224: 還要考慮其他team也太累了吧 如果不是經常要看 為了其他
→ h124224: team寫註解只是浪費時間而已
→ h124224: 應該說，經常有人要第一次看
→ dnabossking: 當注解一堆的時後，他媽就是代表你的code有問題啦，
→ dnabossking: 不想著怎麼把code寫的更簡潔，只想用注解來逃避自己
→ dnabossking: 的爛code真的是超爛的
→ dnabossking: 不是寫注解不好，而是別寫一堆廢注解，還自以爲是在
→ dnabossking: 提聲可讀性
推 t64141: 遇過樓上說的這種，程式一團亂，然後跟我說看他寫的註解就
→ t64141: 知道功能了
推 jack0204: swagger之類的就是要寫註解才有用阿
→ jack0204: PHP很多IDE都是靠註解來判斷函式的，怎麼可能不寫
→ knives: 可是我認為swagger那種PHP Doc 的不是大家討論的那種註解
→ rofellosx: 習慣用建新的code取代修改就沒忘記更新註解問題 即使與
→ rofellosx: 舊的有87%像..
噓 deray: 靠北咧 Phpdoc跟註解不一樣好嗎
推 jack0204: 它不是註解難道是程式碼嗎? 它也是註解的一種阿
→ jack0204: 註解的定義本來就很大，問題是寫到什麼程度而已
→ testPtt: 打在code裡跟程式功能無關的可以當做註解
→ testPtt: 甚至c# attribute 也可以算註解
→ BoXeX: 所以我才說要看團隊狀況
→ BoXeX: 一個專案少說幾萬行  你不加註解同team的還是覺得很好懂
→ BoXeX: 但其他人一但要碰   根本無從下手
→ BoXeX: 更多的是自以為 clean code 不寫註解  結果超 dirty
→ BoXeX: 另外要求新手不加註解的我也不太能體會
→ testPtt: 幾萬行過幾個月回來看就不懂了 就算都自己寫的也一樣
→ deray: Document 跟 Comment 都分不清的話 還有討論的必要嗎？