寫程式 註解真的很重要

老生常談! 但還是要不斷的宣導! 提醒自己也是幫忙降低軟體界的受害人數!

No, Your Code Is Not So Great That It Doesn't Need Comments

以下只是自己的註解的 Style ,跟原文有差異,有興趣可看原文,因為這方面實在是一種人一種想法,反正作法百百種,可以到羅馬就好!

  • 撰寫程式碼前,利用註解寫出大綱,之後在將實作程式碼放在每一行註解下面.
  • 把註解當做便利貼,利用註解幫忙大腦記事情. 你寫上去,就算你還沒編寫相關程式碼,但你一看到註解就可以知道你寫到哪以及該寫啥了!
  • 不要寫沒有意義的註解.
  • 就算能寫出自我解釋的程式碼來替代註解,”但”還是要註解.
  • 註解要隨著原始碼更新(修改/刪除).
  • 程式碼方法介面使用高階概念的抽象名詞,但註解中會寫出實作方式/留下進一步資訊(留下 link).
  • 不怕你寫一堆註解,只怕你都不寫註解.
  • 我都用中文寫註解,因為我不想之後浪費時間去看懂我以前到底再寫什麼英文! Orz

以上! 覺得爛不要醮我!

9 則回應:

SoNys 提到...

最怕的是留下高階概念而抽象的注解...
XD

這種事情我做過

最後還不如去看Code...Orz

匿名 提到...

Right on!
There is no excuse whatsoever for not commenting code, it is just pure laziness and/or sloppiness.
Some people have told me it takes too much time - this is also pure nonsense.
I can, however, understand people if they don't care about the code they write and admit it.

Noid 提到...

嗯...
雖然我只有寫過一點點程式,
不過註解真的有重要
因為有時候連自己也看不懂

現在連改 blog 的CSS 都會註解了~XD

[ 小黑宅 ] 提到...

To SonyChuck
很囧..
這樣等於沒寫註解! Orz

To codeslave
u are Ivan ! XD

To noid
不管是 寫 code 或是 其它方面
有紀律 及 有方式 的隨手記錄
我相信是減少大腦負擔的好方法 XD
PS:
CSS 真的是該寫註解
為何這麼說?
因為我每次都沒寫後來算寬度都算的要死要活

匿名 提到...

我寫程式超不愛寫註解的@@
但看別人的code時又覺得有註解真好XD
看樣子還是站在別人的角度想看看@@
我在前公司寫的code現在應該是塊無法修改的區域吧@@

Unknown 提到...

其實,只要記得後續維護的人是有嚴重暴力傾向的,那...看你寫不寫@_@

[ 小黑宅 ] 提到...

To glayliou
還好我不用看你的code! XD

To 小賤健
通堂我都是看完別人的code才會有暴力傾向! Orz

匿名 提到...

Hi 小黑宅大大,經過了7年的時間,你對這些寫註解的感想是否有些改變呢??

[ 小黑宅 ] 提到...

比較大的改變:
1) 用英文寫註解
2) 盡量 拆分成小方法 和 變數名稱清楚,邏輯上清楚就不寫註解。
3) 能把邏輯寫清楚就盡力寫清楚,盡量不要用到註解。