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

[iincho (世界的盡頭)]

※ 引述《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
推 GX90160SS: 其實很多時候跟每個人所在環境不同關係很大
→ GX90160SS: 舉例就可以看出原PO不是走純軟的吧，應該沒有對程式
→ GX90160SS: 設計規範有所要求，從coding style可窺知一二
 我那也是隨便舉個例子。
 我就表達一件事，再怎麼精心設計變數名稱和流程不可能cover所有case，
 註解不可少，該用就要用。
※ 編輯: iincho (220.134.180.133), 12/30/2018 08:28:27
→ GX90160SS: 有些環境需要review code的機會可能不多就不會注重這塊
  code review我們有做啊，沒加註解一樣會被我踢。
※ 編輯: iincho (220.134.180.133), 12/30/2018 08:30:08
→ GX90160SS: 但也有多人協同工作的公司是天天要整合別人的程式碼
推 GX90160SS: 註解有其必要，但是不是寫了註解就可以對程式可讀性
→ GX90160SS: 便宜行事，註解這東西不像變數可以跟著程式到處跑
 呃..這兩件事根本不衝突啊，沒有人說寫了註解就不需要考慮程式可讀性?
 是有一派堅持寫註解是你程式寫不好這論點比較有問題吧..?
※ 編輯: iincho (220.134.180.133), 12/30/2018 08:39:09
推 superpai: 你想要註解的是why ,  但是-4 是what, 不大相同
推 superpai: 所以-4跟你的100都要命名，然後加上why的註解
 這個我覺得沒啥問題啊，我覺得這個版實在是不知道該怎麼說...
 大家對別人的東西都很picky卻忽視人家要表達的東西...

 以那篇-4或是我這邊寫的100/2000這些東西，不會因為用了define就不需要寫註解。

 至於您有講到一個點，我一直都在說code可以很好表達的是what/how，但是很多情況
 下why只能用註解來處理。
※ 編輯: iincho (220.134.180.133), 12/30/2018 08:46:07
噓 steve1012: 一直戰這種雞毛蒜皮到底要做啥...
→ iincho: 我也覺得這種不衝突的問題發一篇也滿奇怪的..XD
推 hidog: -4如果只用在一個位置,我覺得要不要定義都ok
→ hidog: 雖然我會定義,註解並行. 兩者其實沒衝突
推 deray: 100拉出來變成const EXCEPTION_INTERVAL
→ deray: 加個subFunction check isExceptionOccurred
→ deray: 這麼簡單還要我說
→ xephon: 現在是變成理想派vs實務派大戰?
推 gmoz: EXCEPTION_INTERVAL  再怎樣都會有一個名詞多種腦補解釋
→ gmoz: 註解一行上去就解決了 幹嘛堅持不要?
→ localOjisan: 這個100的例子跟拒絕存取的例子有不一樣嗎？帶有特
→ localOjisan: 殊意義的值為什麼要直接hard code?
推 kokal: 這例子綁定hardware,只有刪除或留著,沒有修改
推 lance70176: 同意你的意見一票
→ rofellosx: 為何不能cover所有case?
→ fgkor123: 韌體常不能cover，粒度不夠+記憶體限制+不一定有os...
→ fgkor123: i/o沒事不會重寫，special case常常比想像的多...
→ viper9709: 推這篇~解說的很好