[心得] 好的註解是解釋為何需要這段 code

cuteSquirrel03/19 22:40第二張 XD

becca94503/19 22:53https://i.imgur.com/4AxoGNi.png

neo527703/19 23:17login(para) //login method

clamperni03/19 23:24tricky的要吧?

cuteSquirrel03/19 23:49貓貓可愛

spfy03/19 23:54以前覺得是笑話 真正遇到之後發現我自己才是笑話...

spfy03/19 23:56兩千多行的遞迴FOR循環 註解寫//循環讀資料 幹你娘

cuteSquirrel03/19 23:57XDDDDDDDDD

drajan03/20 00:00認同

chuegou03/20 00:09#define ZERO 0 //origin

ctrlbreak03/20 00:10註解都是在罵老闆、表同事

Sixigma03/20 00:34最好的code本身應該要解釋它自己，很多註解很容易寫廢話

cuteSquirrel03/20 00:36真的 看到self-explanatory code效率高很多

drajan03/20 00:37Code 只能解釋 what 註解跟文檔可也解釋 why

pikaka03/20 00:51本文有提到不要盡相信code即是註解 就是因為

pikaka03/20 00:51沒有那麼多最好的code阿XD

pikaka03/20 00:57能在註解多給可能有用的資訊 對後面接手的人都是有幫助的

Sixigma03/20 01:10我同意沒那麼多"最好"的code，但這是可以改進的方向

wawi203/20 01:22可是一堆人寫的code就是讓人看不懂阿 阿對了 有些人英文

wawi203/20 01:22不太好 寫了註解也是讓人沒看懂

anandydy52903/20 02:26//下班前突然來一顆隕石，所以這樣寫才能正常下班

t2225197403/20 02:34謝謝分享

VdustR03/20 04:18code 可以自己解釋在做什麼 註解用來解釋為什麼要這樣做

VdustR03/20 04:20cra 的註解就很棒 https://tinyurl.com/2w6wd9re

jobintan03/20 06:52安心しろ！老闆要是刻意挑刺，無論註解解釋的再清楚總是

jobintan03/20 06:53會有意見的。

jobintan03/20 06:55只是清楚的註解讓後面接手能短痛接手，就寫進linked in

jobintan03/20 06:55 profile裏面，當做自己的credit。

aidansky098903/20 08:14同意，很多code需求都要寫清楚，沒有註解靠通靈

hduek15303/20 08:50//不知道為什麼加了這行才能動

OrzOGC03/20 08:56對不起 我也這樣寫...QQ

mathrew03/20 09:08//Google到的，我也不知道為什麼

v7q403/20 09:45// for test

v7q403/20 09:46結果那行拿掉就掛了…明明是必要的啊！為何要寫for test....

ssd860505da03/20 09:55貓咪<3

stupid031903/20 10:21// something to do

superpandal03/20 10:31有看過解釋來龍去脈很多行但如同沒講的狀況嗎？ 個人

superpandal03/20 10:32還是習慣Keep it simple and flexible

leo591626703/20 10:45我覺得註解可以寫這程式用在哪裡，比寫他在幹嘛好，

leo591626703/20 10:45程式在幹嘛應該表現在命名上

t1996080403/20 10:48//shit code

superpandal03/20 10:53用在哪與在做什麼很容易寫的差不多 命名也要看長度

superpandal03/20 10:54駝峰命名太長會很悲劇 唯一支持_

superpandal03/20 11:00不過已有的系統就沒辦法了 全小寫+下劃線非常清爽 眼

superpandal03/20 11:00球無壓力

bronx080703/20 11:03if {...} // end of if

howard5000903/20 11:17同意，推這篇

lturtsamuel03/20 11:42看過最實用註解是 // 千萬別在這函式前 aquire mutex

energyy110403/20 11:48//stackoverflow的連結

shibin03/20 12:07同意，謝分享

SKII58803/20 12:08需要撇清責任時會寫，某年某月某董要求修改之類的

CarpeDiemAL03/20 12:35// Wtf is this? stubbed.

molopo03/20 12:56//我先走了 剩下交給你了

Csongs03/20 12:57//看不懂 塊陶啊

WaterLengend03/20 12:59認同

foodordertw03/20 13:33// here could be a bug

lee45708803/20 13:39// Pasted from web. Idk why it works.

Nigger556603/20 13:58// 幹你老師好想下班

leftless03/20 14:47//SNIS-OOO

cuteSquirrel03/20 15:03// just workaround

online13503/20 15:51// 垃圾欺負新人的 senior 都去死

WunoW03/20 16:06樓上怎麼了??

Muscovy03/20 16:18我看過想一套, 寫一套, 註解一套, 每套不一樣還分版本.

Muscovy03/20 16:19最好玩的是程式跑起來還沒問題...

hamster393303/20 16:50推

online13503/20 17:52沒有我留錯地方了哈哈哈

v7q403/20 18:15http://i.imgur.com/b5mI5Kh.jpg

abc092200103/20 18:47我抱怨需求都是寫在 commit 裡

jobintan03/20 19:51哪天幹得不爽，在離職走人前將重要的code全註解掉。（誤

jobintan03/20 19:54BTW，整串的怨念感覺深不見底，之前看過TechLead的影片

jobintan03/20 19:55也許能參考下，網址在此：

jobintan03/20 19:56https://ptt.cc/fXESYx

jobintan03/20 19:59不然去YT搜" anti-patterns techlead"就找得到了。

jobintan03/20 20:00這招註解還狠…

wulouise03/20 21:37linux kernel有一行程式配五十行註解說不用lock的原因

wulouise03/20 21:37靠腰按錯碰到噓，等等補推

wulouise03/20 21:45補推

jamesho874303/20 22:13是不要相信註解即是code吧 code本來就是絕對存在的 c

jamesho874303/20 22:13ode才是真正在run的 註解並不靠譜

jej03/20 23:13// 我在絕情谷底 嗡嗡嗡

marc4703/21 01:06如果你有寫過go的code你就不會這樣說了，光是變數明名跟fu

marc4703/21 01:06nc動名詞，就可以寫完詳細的說明文件，然後加上func的標記

marc4703/21 01:06註解及一個README.md就整份文件寫完收工

lturtsamuel03/21 01:44我看你是沒看過兩個go channel互相咬住 要寫註解警告

lturtsamuel03/21 01:44接手者不要在一個channel返回前往另一個channel塞值

twonia03/21 08:16我覺得適度可以，但多半是大公司內被轉了不知道幾手的Code

twonia03/21 08:16中間改的人不見得有維護註解，也不是人人都有能力寫好讓人

twonia03/21 08:16可以理解用途的Code，更該是個相輔相成的東西

azureroki03/21 08:30看過寫//獨立 的...

ketrobo03/21 10:15// 不寫不能下班

markbex03/21 14:15code只能解釋做了什麼 但無法解釋為什麼這麼做

markbex03/21 14:15把意圖、Why要寫在註解裡面，常常幫助到的是未來的自己

leolarrel03/22 10:33#不知道為什麼不能用//當註解,所以就改成#

leolarrel03/22 10:34針對markbex大大的需求,版控summery更加的適合

MoonCode03/22 12:13提到golang直接看標準庫

MoonCode03/22 12:13https://golang.org/pkg/net/

MoonCode03/22 12:13註解寫非常多而且詳細

MoonCode03/22 12:14有誰可以只用code表達所有事物的人我只能說你厲害喔

jobintan03/22 12:25光看Code不看註解就知道這段Code是作啥，那也很強大。

shooter55503/22 13:47只看code可以理解他做啥 厲害的不是看得人 是寫的人

shooter55503/22 14:02不相信註解不是因為能不能寫的詳細 是因為通常會忘了

shooter55503/22 14:02維護

jamesho874303/22 16:02註解的問題是有可能誤導 有維護性的問題 就算它寫的

jamesho874303/22 16:02時候是ok的 但後來code變更時註解是否也同時更新?

jamesho874303/22 16:02 註解跟code不一樣時還不是得看code

lwecloud03/22 16:56//Magic number

pikaka03/22 19:22樓上提到維護性的問題 code本身也有阿 什麼東西不好好維護

pikaka03/22 19:22都會遇到問題 這種情況有問題的都是人 不是這工具

s091471403/23 01:08//更多更詳盡程式碼 在Stack Overflow

s091471403/23 01:11code是本體 註解是輔助讓code更完善 彼此相輔相成

jamesho874303/23 08:31這個所說的維護性問題應該是說一致性問題 code沒有一

jamesho874303/23 08:31致性問題 不管寫得再爛 它跟實際上run的是完全一致

jamesho874303/23 08:33因為一致性問題 所以註解要隨時維護得跟code一樣

cha12297703/23 09:04註解麻煩在維護 當然可以說我看code最準哪需要管註解

cha12297703/23 09:05但不一致時你不知道是code寫錯了 還是註解沒更新…

jamesho874303/23 20:44這就是註解麻煩的一面 容易誤導 基本上code"不會錯"

jamesho874303/23 20:44 註解可以無視 code 就是現在run起來的樣子 如果不

jamesho874303/23 20:44對不符合需求 就改code

jamesho874303/23 20:49註解跟code不一致時 基本上你根本不要管註解 因為註

jamesho874303/23 20:49解通常是更新度比不上code 你要做的只是把code run

jamesho874303/23 20:49 一遍 看看是不是符合預期 在意註解變成它在混淆你

jamesho874303/23 20:54所以說為什麼註解最好只解釋架構或者作者的意圖 不要

jamesho874303/23 20:54去寫太過細節的東西 因為架構跟意圖通常不容易隨時

jamesho874303/23 20:54間而改變 要把註解的其它功能 放在把code寫得清楚易

jamesho874303/23 20:54懂上面 清楚易懂的code本身就是一種註解

yyc121703/23 21:08更多的是覺得自己寫得很好所以不用加註解

b8504031203/23 21:17像我公司都直接不註解的 註解還會被嗆，看 code 就不好

cuteSquirrel03/24 12:03哈 還有遇過會刪註解的 XDDDDD

shooter55503/24 13:04註解就是用來//WORKAROUND:XXX //TODO:XXX //FXCK:XXX

shooter55503/24 13:07用來解釋給後面維護的人知道原因 以面被罵 那個廢物前

shooter55503/24 13:07輩寫這什麼鬼扣

shooter55503/24 13:08 以免

jamesho874303/24 18:19The code is right there, we know what it does. 英

jamesho874303/24 18:19語這兩句講得很好 都講完了

mrnegativetw03/25 18:48// TODO

mmppeegg03/29 14:30註解好好寫啦 對你自己好

mmppeegg03/29 14:30不要哪天你回來看你自己的code都看不懂

viper970903/29 23:56推樓上

BoXeX04/01 15:14你的code功能太簡單才能光靠code表達 常常一些code都是

BoXeX04/01 15:14為了某個special case存在的 不靠註解誰知道用意

BoXeX04/01 15:14當然也可以靠commit講啦 但對讀的人來說就是麻煩

BoXeX04/01 15:16在那邊說好的code不需要註解的 往往只是給自己的懶惰找

BoXeX04/01 15:16藉口

molopo01/19 12:44拜託不寫註解 亂命名的 獨立接案就好 不要出來害人好嗎