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

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