作者iincho (世界的盡頭)
看板Soft_Job
標題Re: [請益] 寫註解到底是不是好習慣
時間Sun Dec 30 07:41:26 2018
※ 引述《accessdenied (存取違規)》之銘言：
: 這邊怎麼老是吵著小孩子頭上有幾根毛的問題。
: 說不用註解的，都是英雄主義作祟，自己因為自己的程式碼天下最簡潔易懂，這種看不清
: 自己的人還挺多的。
: 團隊合作就是要註解，除非你不在乎團隊！
: 你以為大家都是你肚子裡的蛔蟲？
: 我光是寫一行code：
: key = salt + DateTime.Now.AddHours(-4).ToString(“MMdd”);
: 就會一直有人來問為什麼要這樣寫，-4什麼意思？
: 最後我加上一行註解從此耳根清淨
: // 廠商要求每天清晨4點以後要更換加密金鑰
: 大家講了半天，註解只有一個缺點，就是過時美人維護。而我認為這才是真正該教育改善
: 的文化和心態：不是我寫的註解，所以我沒有維護的責任。
: 這才是真正的弊端，而不是倡導clean code。
這個例子舉得蠻好的，很多時候我們實務上面對的問題不是單靠命名就可以解決，
因為很多問題沒有邏輯性。
比如說我有個機器硬體設計可能有問題，操作100次的時候需要有一個例外操作，
這個code可能會長成:
for(int i = 1 ; i <= 2000; i++){
if(i % 100 == 0){
DoSomethingElse();
}else{
DoSomething();
}
}
這種case你要怎麼命名? 這可能是個hardware bug，你確定你要在變數
裡面解釋這是一個hardware bug嗎? 這個case跟上面舉的-4基本是同一類的，
你變數再怎麼命名都不會比寫註解清楚。因為實務上我們會想要提醒接手
的人這個hardware bug長什麼樣子，如果有做類似的操作要怎麼避開，
這不用註解是不大可能做得到的。如果你說可以寫在commit log...
ㄛ...我們好像有客戶還在用svn...
這種例子我覺得不能算是magic number，本質上不管你怎麼define都解釋不清楚，
用define的好處就是集中管理方便重用而已。真的要解釋中間插兩行issue number
簡單說一下都好，在那邊落落長想code怎麼命名花的時間不會比較少，
何況別人讀你的code的時候看註解比看code上下文猜容易太多，
這個case就算加了define命名還是需要寫註解。
BTW, 程式寫註解和做好變數和流程命名根本就不衝突，兩者是互補而不是競爭關係。
我不知道這邊為什麼會有寫哪一種比較好的爭論，實務上兩個都需要，
哪個經濟用哪個。
另外我真的覺得很好奇想認真問一下，各位真的覺得那個-4在那邊取什麼
DailyRest之類的東西繞來繞去有比加一行註解好嗎...??
先不要說是不是大砲打小鳥這問題，code沒有比較好讀啊。
--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 220.134.180.133
※ 編輯: iincho (220.134.180.133), 12/30/2018 08:24:29
1F：推 GX90160SS: 其實很多時候跟每個人所在環境不同關係很大 12/30 08:25
2F：→ GX90160SS: 舉例就可以看出原PO不是走純軟的吧，應該沒有對程式 12/30 08:26
3F：→ GX90160SS: 設計規範有所要求，從coding style可窺知一二 12/30 08:26
我那也是隨便舉個例子。
我就表達一件事，再怎麼精心設計變數名稱和流程不可能cover所有case，
註解不可少，該用就要用。
※ 編輯: iincho (220.134.180.133), 12/30/2018 08:28:27
4F：→ GX90160SS: 有些環境需要review code的機會可能不多就不會注重這塊 12/30 08:29
code review我們有做啊，沒加註解一樣會被我踢。
※ 編輯: iincho (220.134.180.133), 12/30/2018 08:30:08
5F：→ GX90160SS: 但也有多人協同工作的公司是天天要整合別人的程式碼 12/30 08:30
6F：推 GX90160SS: 註解有其必要，但是不是寫了註解就可以對程式可讀性 12/30 08:34
7F：→ GX90160SS: 便宜行事，註解這東西不像變數可以跟著程式到處跑 12/30 08:34
呃..這兩件事根本不衝突啊，沒有人說寫了註解就不需要考慮程式可讀性?
是有一派堅持寫註解是你程式寫不好這論點比較有問題吧..?
※ 編輯: iincho (220.134.180.133), 12/30/2018 08:39:09
8F：推 superpai: 你想要註解的是why , 但是-4 是what, 不大相同 12/30 08:39
9F：推 superpai: 所以-4跟你的100都要命名，然後加上why的註解 12/30 08:42
這個我覺得沒啥問題啊，我覺得這個版實在是不知道該怎麼說...
大家對別人的東西都很picky卻忽視人家要表達的東西...
以那篇-4或是我這邊寫的100/2000這些東西，不會因為用了define就不需要寫註解。
至於您有講到一個點，我一直都在說code可以很好表達的是what/how，但是很多情況
下why只能用註解來處理。
※ 編輯: iincho (220.134.180.133), 12/30/2018 08:46:07
10F：噓 steve1012: 一直戰這種雞毛蒜皮到底要做啥... 12/30 08:57
11F：→ iincho: 我也覺得這種不衝突的問題發一篇也滿奇怪的..XD 12/30 09:07
12F：推 hidog: -4如果只用在一個位置,我覺得要不要定義都ok 12/30 09:59
13F：→ hidog: 雖然我會定義,註解並行. 兩者其實沒衝突 12/30 10:00
14F：推 deray: 100拉出來變成const EXCEPTION_INTERVAL 12/30 11:56
15F：→ deray: 加個subFunction check isExceptionOccurred 12/30 11:57
16F：→ deray: 這麼簡單還要我說 12/30 11:57
17F：→ xephon: 現在是變成理想派vs實務派大戰? 12/30 12:26
18F：推 gmoz: EXCEPTION_INTERVAL 再怎樣都會有一個名詞多種腦補解釋 12/30 12:43
19F：→ gmoz: 註解一行上去就解決了 幹嘛堅持不要? 12/30 12:43
20F：→ localOjisan: 這個100的例子跟拒絕存取的例子有不一樣嗎？帶有特 12/30 14:01
21F：→ localOjisan: 殊意義的值為什麼要直接hard code? 12/30 14:01
22F：推 kokal: 這例子綁定hardware,只有刪除或留著,沒有修改 12/30 14:23
23F：推 lance70176: 同意你的意見一票 12/30 14:53
24F：→ rofellosx: 為何不能cover所有case? 01/02 09:02
25F：→ fgkor123: 韌體常不能cover，粒度不夠+記憶體限制+不一定有os... 01/04 07:48
26F：→ fgkor123: i/o沒事不會重寫，special case常常比想像的多... 01/04 07:49
27F：→ viper9709: 推這篇~解說的很好 01/04 22:24