在"這裡"看到的..

註解的目的

註解是用來寫目的、限制條件跟預期結果等，而不是寫出以下這些程式一行行會做些什麼(請不要拿註解再寫一次程式碼在寫的事情)。一個簡單的判斷方式是：寫在函式 “裡面” 的註解多半是不需要的 (尤其是註解寫 what? 而不是註解 why?)。在重構一書更直言回答哪裡需要重構？那就是有註解的地方：如果程式碼前方有一行註釋，就是在提醒你，可以將這段程式碼替換成一個函式，而且可以在註釋的基礎上給這個函式命名。

你要做的事情應該是讓 source code 本身容易了解，而不是透過註解。透過正確的變數命名、好的空白間隔、邏輯分離清楚的執行路徑等手法，我們很少需要在函式裡面註明這些程式在做什麼，我自己的經驗除非是有參考外部的程式碼或複雜演算法，我會多註明參考來源(網址)。否則沒有必要的註解對我來說就像噪音一樣，妨礙閱讀。

最佳的註解就是程式碼。所以要寫出別人看得懂的code，比較重要 -- 但這往往是不容易的，也無法列出規定，所以，有些人就只好從coding style 中規定一堆...
結果，規定的都是一些不著邊際的rule..