作者ripple0129 (perry tsai)
看板Soft_Job
標題Re: [請益] 寫註解到底是不是好習慣
時間Thu Dec 27 23:50:54 2018
這種討論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://webptt.com/m.aspx?n=bbs/Soft_Job/M.1545925856.A.7C1.html
1F：→ testPtt: 我是會做相依性註解 程式改這種註解難免要改12/28 00:17
2F：推 piadora: 請問有什麼工具可以幫助畫圖12/28 00:40
譬如說
VS的Code maps
PHP RIPS
※ 編輯: ripple0129 (1.171.204.87), 12/28/2018 01:06:36
3F：推 BoXeX: 我是覺得跟開發環境和團隊狀況有關 12/28 01:13
4F：→ BoXeX: 當整個團隊能用的工具越少 就越需要註解來幫忙 12/28 01:14
5F：→ BoXeX: 還有如果要給其他團隊看的 多一點註解可以幫助理解 12/28 01:15
6F：→ BoXeX: 同team的人習慣接近了 覺得clean到不行 12/28 01:16
7F：→ BoXeX: 換個團隊看就變成無字天書 12/28 01:16
8F：推 h124224: 還要考慮其他team也太累了吧 如果不是經常要看 為了其他 12/28 04:59
9F：→ h124224: team寫註解只是浪費時間而已 12/28 04:59
10F：→ h124224: 應該說，經常有人要第一次看 12/28 05:00
11F：→ dnabossking: 當注解一堆的時後，他媽就是代表你的code有問題啦， 12/28 09:15
12F：→ dnabossking: 不想著怎麼把code寫的更簡潔，只想用注解來逃避自己 12/28 09:15
13F：→ dnabossking: 的爛code真的是超爛的 12/28 09:15
14F：→ dnabossking: 不是寫注解不好，而是別寫一堆廢注解，還自以爲是在 12/28 09:19
15F：→ dnabossking: 提聲可讀性 12/28 09:19
16F：推 t64141: 遇過樓上說的這種，程式一團亂，然後跟我說看他寫的註解就 12/28 09:23
17F：→ t64141: 知道功能了 12/28 09:23
18F：推 jack0204: swagger之類的就是要寫註解才有用阿 12/28 09:28
19F：→ jack0204: PHP很多IDE都是靠註解來判斷函式的，怎麼可能不寫 12/28 09:28
20F：→ knives: 可是我認為swagger那種PHP Doc 的不是大家討論的那種註解 12/28 09:30
21F：→ rofellosx: 習慣用建新的code取代修改就沒忘記更新註解問題 即使與 12/28 09:39
22F：→ rofellosx: 舊的有87%像.. 12/28 09:39
23F：噓 deray: 靠北咧 Phpdoc跟註解不一樣好嗎 12/28 10:03
24F：推 jack0204: 它不是註解難道是程式碼嗎? 它也是註解的一種阿 12/28 10:17
25F：→ jack0204: 註解的定義本來就很大，問題是寫到什麼程度而已 12/28 10:19
26F：→ testPtt: 打在code裡跟程式功能無關的可以當做註解 12/28 10:36
27F：→ testPtt: 甚至c# attribute 也可以算註解 12/28 10:37
28F：→ BoXeX: 所以我才說要看團隊狀況 12/28 11:39
29F：→ BoXeX: 一個專案少說幾萬行 你不加註解同team的還是覺得很好懂 12/28 11:41
30F：→ BoXeX: 但其他人一但要碰 根本無從下手 12/28 11:42
31F：→ BoXeX: 更多的是自以為 clean code 不寫註解 結果超 dirty 12/28 11:45
32F：→ BoXeX: 另外要求新手不加註解的我也不太能體會 12/28 11:47
33F：→ testPtt: 幾萬行過幾個月回來看就不懂了 就算都自己寫的也一樣 12/28 11:53
34F：→ deray: Document 跟 Comment 都分不清的話 還有討論的必要嗎？ 12/28 12:10