推 ThxThx: 同意這篇。這個問題Reddit也有許多討論，像這篇 12/29 14:57
→ viper9709: 推整人 01/01 23:35
我覺得要定義註解內容是什麼
如果只是描述程式語法架構本身的東西，不是那麼重要
但是有些註解是說明為什麼要寫這行
原因與程式碼本身語法無關
比如註解:這行可暫時避免每一百次會出現一次硬體當機的問題…
又或是:這行是為了滿足a廠商的規格…
還有，人都有失憶症，你的程式碼很複雜時，註解可以讓你過了一年再review時大幅縮短時
間
然後如果是多人一起開發的大型軟體需要整合，都不寫註解，那就不是整合是整人了，當然
可以寫一份api說明文件取代註解…
以前有聽過國外大型軟體公司， 要求工程師寫的程式碼註解字數一定要佔檔案10%以上，還
用工具去自動檢查有沒10%…
※ 引述 《sec5566 (sec)》 之銘言：
: 標題: [請益] 寫註解到底是不是好習慣
: 時間: Thu Dec 27 13:48:31 2018
:
:
: 以前上課跟書本都提到寫註解，
: 但是我看資深同事還有接手的程式碼，
: 都沒有註解，只有我在寫，
: 還被主管念過寫註解沒必要，
: 命名好就夠了，
: 是我觀念落伍了嗎？
:
: -----
: Sent from JPTT on my Sony H4331.
:
: --
: ※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 223.140.72.67
: ※ 文章網址: https://www.ptt.cc/bbs/Soft_Job/M.1545889713.A.2B5.html
: ※ 編輯: sec5566 (223.140.72.67), 12/27/2018 13:48:43
: 推 t64141: 想不寫註解有很多前提，而這個前提不容易達到 12/27 13:54
: 推 oneheat: 好的代碼很少在寫註解，或者說，code都寫不好了，為什麼 12/27 13:55
: → oneheat: 會覺得註解會寫的好呢？ 12/27 13:55
: → BeardSmallGG: 有寫註解讓其他人比較省時吧 五六行的程式 一句註解 12/27 14:02
: → BeardSmallGG: 就知道在幹嘛了 有時候哪有時間在那邊一行一行看 12/27 14:02
: 推 steve1012: 需要很多註解常常不是件好事 12/27 14:07
: 推 deray: 寫什麼註解？貼一段來看一下為什麼需要註解 12/27 14:11
: 推 yyc1217: 覺得自己寫的很好就不寫註解 這種人很有問題 12/27 14:12
: → yyc1217: 覺得自己寫得不好而寫一堆註解 這種人也很有問題 12/27 14:13
: → iiiii: 寫SAMPLE CODE一樣道理，曲高和寡，不是人人懂你的pattern 12/27 14:14
: → yyc1217: 註解是寫給三個月後的自己看的 12/27 14:15
: 推 steve1012: 不過這樣討論都打高空啦 除非你貼一段被念的程式跟註 12/27 14:21
: → steve1012: 解 12/27 14:21
: 推 stupid0319: 多練習爬code不看註解吧 12/27 14:22
: 推 kokacal: git log是很好用的東西，每個人都在程式碼內註解一段， 12/27 14:24
: → kokacal: 那到底是要看程式還是看註解 12/27 14:24
: → femlro: 蘋果官方的code都有註解了 不寫註解超越蘋果 12/27 14:32
: 推 deray: 註解！=文件 12/27 14:35
: → askaleroux: 我只有Unittest寫註解 12/27 14:38
: 推 thefattiger: 我覺得至少在func/cls開頭簡單地寫一行這是拿來幹嘛 12/27 14:39
: 推 jknm0510a: 我是會在比較複雜的判斷上寫註解，以後看比較不用思考 12/27 14:39
: → thefattiger: 可以節省讓後來閱讀的人節省很多時間及不必要的猜測 12/27 14:40
: 推 hotdogmc: 程式碼本身就是註解 12/27 14:47
: 推 Argos: 要看情況阿 你是要出API 沒註解行麼？ XD 12/27 14:48
: 噓 abc0922001: 洗文章嗎 12/27 14:49
: → Argos: 內部產品程式 註解有必要再加吧 有些潛規則不講很麻煩 12/27 14:49
: 推 sean2449: 自以為寫很好不用寫註解的很多+1 通常就是...自以為 12/27 15:00
: 推 yesyesyesyes: 要拜託 12/27 15:04
: 推 KanzakiHAria: 拜託要+1 12/27 15:19
: → KanzakiHAria: 命名到為還是需要註解 因為每個人邏輯不一樣 12/27 15:19
: → deray: 「當程式碼與註解不符時，你相信什麼？」 12/27 15:20
: → deray: 「The ultimate comment for the code is the code itself 12/27 15:20
: → deray: 「註解是用來『彌補我們用程式碼表達意圖的失敗』」 12/27 15:21
: → knives: 推樓上加一，商業邏輯可以另外寫在文件上去交接 12/27 15:21
: 推 LoserWon: 會寫註解的，寫出去的註解越多，回來問的越少 12/27 15:29
: 推 ymcheung: 換上有意義的命名後 註解的份量就變少了 12/27 15:38
: → rofellosx: 並不會少.. 12/27 15:40
: → dnabossking: 把code寫的爛的一b然後跟你說：「我有寫注解」看完 12/27 15:42
: → dnabossking: 注解再看code發現注解根本在誤導（你根本沒有任何方 12/27 15:42
: → dnabossking: 法保證注解的正確性跟易懂）這種人我也見過不少就是 12/27 15:42
: → dnabossking: 了 12/27 15:42
: 推 vi000246: 直接註解寫文件位置 要看邏輯自己去查文件 12/27 16:02
: 推 exeex: 先養成"程式即是註解"的code style 12/27 16:05
: 推 iamshiao: 特殊處理寫，其他不寫 12/27 16:15
: 推 kevin28: 比較複雜的邏輯才會寫 12/27 16:18
: 推 sean50301: 看情境xd 建dl模型註解一下shape 後面的人會很感謝你 12/27 16:44
: → KanoLoa: 當然要寫阿，寫個magic搞搞後人 12/27 17:06
: 推 twilighthook: 要拜託 文件也要寫一下 12/27 17:07
: → twilighthook: 不然看到A05_001.java 這樣的沒註解沒文件鬼才知道 12/27 17:07
: → twilighthook: 是要做啥的 12/27 17:07
: 推 sachung28: 至少函式要寫註解說明功能 和input/output吧 12/27 17:17
: 推 ekin1983: 我的註解通常只寫什麼時間 為何而改(bug 資安 需求單) 12/27 17:19
: → ekin1983: 還有每個function上方註明用途 12/27 17:21
: 推 channaiN2: 個人覺得都可以 不管寫不寫註解 只要你的code讓人不好 12/27 17:24
: → channaiN2: 懂 那就有改進的空間 不管是加註解或是重構 12/27 17:24
: 推 PoloHuang: 寫了註解 結果之後程式有改結果註解沒跟著改 12/27 18:03
: → robber1234: 4 12/27 18:44
: 推 fanatics5566: 只有複雜的邏輯 或 work around的部分會寫而已 12/27 18:44
: → testPtt: 註解寫得好下次回來改東西就很好進入狀況 12/27 18:52
: → CaptainTeemo: 那有做 code review 嗎？有確保不解說的情況下對方 12/27 18:55
: → CaptainTeemo: 能看懂嗎？ 12/27 18:55
: → testPtt: 尤其像C#註解還有函式超連結功能 追程式碼方便很多 12/27 18:59
: 推 codehard: 可以寫pseudo code當註解 12/27 19:19
: 推 overhead: 註解是用來『彌補我們用程式碼表達意圖的失敗 12/27 19:53
: 推 shortoneal: 你把code貼上來，不然會淪為各說各話 12/27 20:40
: → shortoneal: 我有看過code寫得還行購簡潔，可是註解寫好幾行的 12/27 20:40
: → shortoneal: (然後還是很整齊) 12/27 20:40
: 噓 THEWORLDS: 菜逼巴CODE都寫不好了還不寫注解 多可憐 沒看過大專案? 12/27 20:52
: 推 vn509942: 註解可以畫宗教神祇保佑大家身體健康 12/27 20:58
: 推 gino0717: 註解應該寫中文還英文 寫英文英文太爛人家看不懂怎麼辦 12/27 21:22
: → f496328mm: 要寫技術文件，註解還好，code 架構寫得好就夠了 12/27 21:27
: 推 chuegou: 前輩寫得asm沒註解 看到快瘋掉 12/27 21:36
: 推 chuegou: 尤其硬體相依的設計 沒註解我甚至該問ME還是EE都不知道 12/27 21:40
: 推 ChungLi5566: 不要在註解寫一堆東西 最好用兩行表示整個方法 12/27 22:38
: 推 justben: 有magic number 的時候 再寫就好了 12/27 23:12
: → justben: XDD 12/27 23:12
: 噓 xxtuoo: 幾乎全部專案都我一個人維護的..寫屁Zzz 12/27 23:36
: → y3k: 不管Code還是註解 有必要才寫 有必要必寫 12/27 23:42
: 推 molopo: 你不寫 你同事也不寫 可以公告一下你哪間公司嗎 未來不想 12/27 23:44
: → molopo: 去 12/27 23:44
: 推 lausai: 註解是需要的 不過註解的用處是說明程式碼作了甚麼 為什麼 12/28 00:26
: → lausai: 這麼作 而不是怎麼做 12/28 00:27
: 推 lausai: 不過覺得助解不需要的主管...不塊陶嗎XD 12/28 00:29
: → gino0717: 如果當上主管就可以說 自己的code是clean code 不用註解 12/28 00:35
: → gino0717: 你們底下基層都是dirty code 都給我寫好寫滿 12/28 00:35
: 推 CloudyWing: 我比較少寫這段程式碼是幹嘛的，但會寫為什麼要這麼做 12/28 01:01
: → CloudyWing: 註解要寫到到如何見仁見智，但有些寫法我不敢苟同... 12/28 01:03
: → CloudyWing: 像是說要寫註解好維護，寫一大堆，結果註解沒好好維護 12/28 01:06
: → CloudyWing: 或著寫Log時，上行來個//Log，return來個//return 12/28 01:07
: → CloudyWing: 然後最近對於一個class裡有滿滿的regin感到很不耐煩 12/28 01:10
: → coldreflect: 看公司環境，很多時候寫註解commit log是紀錄口頭溝 12/28 01:13
--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 223.138.125.187
※ 文章網址: https://www.ptt.cc/bbs/Soft_Job/M.1546056944.A.99E.html