學生的時候，老師強調code要加上註解。工作初期我也是這麼認為的，但到現在我開始動搖了。因為我的工作要改很多人的code，他們雖然也有註解，但還是很難懂。這種感覺就像一個人不會表達，就算他再多解釋好幾句話，還是聽得霧煞煞。
我現在的結論是，如果程式本身寫得好，不用註解也沒關係。架構清晰、邏輯分明，一眼望去就知道在做什麼。而類別、方法、變數一開始就妥善命名，根本不用看註解就知道意思了。只剩下少數特別情況才需要用註解加以說明。
反觀有的程式寫得莫名其妙。已經一行一行讀，也有註解，但心中還是充滿問號。更多的是為註解而註解，重複無意義的廢話，如下：
int sum; // sum of value
// get the name
String name = getName(id);
最後個人對中文註解比較有感，畢竟我們母語是中文，相當於替我們翻譯好。但看習慣程式的人沒差，以及某些公司或系統禁止中文註解。小弟菜雞，不曉得各位前輩們怎麼想？
已邀請的邦友 {{ invite_list.length }}/5
註解的目的是幫助接手維護的工程師，包含自己 (?) 快速了解程式目的。
注意這裡講的是工程師，不是對程式語法有疑問，甚至連 Domain 單字都還沒建立的人。
結論上來說，需要寫註解的程式段落很少
(像是正規表示式等，可參閱 Clean Code 書中的舉例)，
比起怕麻煩就寫註解甚至無腦就寫，
更該思考的是能否調整命名或重構程式使結構與邏輯清晰的展現。
Don't comment bad code - rewrite it.
by Brian W. Kernighan, P.J. Plaugher
請記得，註解既然寫在程式裡，也是需要維護的，否則必定發生註解騙人的情況，
那在 Code review 中會是非常無言的情境...
難道要 Tech Lead 花時間去追究上一個修改者，為甚麼沒有同時去維護某段註解嗎?
(而這類錯誤只會一再發生，不刪除註解則無法根治，追究也只是浪費時間)
最後，真要註解，語言的採用還是英文為好，省去閱讀者的轉換。
(除非你是用什麼吾有一術。名之曰!@#$%^^&)
補充個，若有導入測試機制的話，測試程式就是最好的註解。
請問為什麼測試程式就是最好的註解？
以單元測試來說，
每個需要寫測試的方法，都會寫出一至多個測試方法，每一個去測試一個情境。
當然，每個測試方法都有名字，規範就看各個團隊去制定，像是
test[MethodName]Should[ResultName]When[ConditionName]() {...}
[MethodName]Should[ResultName]When[ConditionName]() {...}
when[ConditionName]Test[MethodName]Should[ResultName]() {...}
// ...
當測試完善時，我們就可以透過測試程式的名字了解被測試方法會需要驗證那些情境 (Condition -> Result)。
反過來說，這些不就正好是被測試方法需要實現的邏輯了嗎?
而且還是根據情境條列式的，比起註解的英文段落更加易讀好懂且真實。
這就是最好的註解 (易讀/真實)。
所以以單元測試來說，那些有被測試到的方法，完全不應該再用註解去解釋程式目的，那只會造成混淆 (來自英文段落理解能力差異的混淆) 與維護上的困難 (註解騙人/需要額外維護註解)。
菜雞+1
以下我的想法
只要5年後的你回頭看時還看的懂你當年在寫什麼就不用註解了
有時候在開發的時候因為只專注某個片段，
註解通常也只會針對這個片段的當下動作進行註解~
但函數是個黑箱子，
箱子內每一步註解再多，
不如告知這個箱子是在做什麼的，
這我覺得相對比較重要~~
我現在的結論是，如果程式本身寫得好，不用註解也沒關係。架構清晰、邏輯分明，一眼望去就知道在做什麼。而類別、方法、變數一開始就妥善命名，根本不用看註解就知道意思了。只剩下少數特別情況才需要用註解加以說明。
其實您自己應該有結論了
導入git版控後，要求commit message寫清楚點，其實規格修改的註解可以少寫很多甚至不寫。
不過一些『自己找到的參考』拼出來的 code 還是註明一下出處（官網api就不必了）。
至於自己所獨創的演算法，當然一定要註解說明一下，不然未來一定會失傳。
我認為如果程式碼簡單到一眼就看的出來寫的人想表達的，那註解就不是必要的。
註解可以幫助我們在閱讀一份程式碼時，更快的理解撰寫者的用意，如果他不是亂寫的話。
通常是複雜邏輯，需要看一段時間才能搞懂程式碼在寫什麼，那麼註解可以幫助我們加快理解速度；或者是規範上的需求，例如這個變數為什麼在這裡會是這個值，在那裡又是另一個值，讓看的人不需要再去翻規範。
我只會在程式開始寫註解，大概寫這隻程式的功能、日期、編修原因、要求編修的人，影響的範圍。
另外在函數的起頭寫註解，及特殊段落與語法會特別註記。
註解除了要讓自己快速了解這個程式結構外，還有方便後面接替維護的人員，這是寫註解的人要注意的，所以寫註解除了自己要能看得懂外，如何能讓人能夠讀得懂註解，這才是真功夫。
不是只會寫程式才厲害，能夠讓人透過註解來解讀並修改你的程式，才是真正厲害的人。
PG常覺得寫的func包含細部邏輯都很容易理解，所以不寫註解，
但不要太高估別人理解能力
你覺得很好懂，但code自己寫的當然好懂，我也覺得我寫得很超直白容易理解
但資深同事還是會來問我，還要花時間跟他解釋及拿範例出來，那我註解就好啦
所以我是習慣寫註解，不論該func或較特別邏輯運算時，方便自己金魚腦以後還看得懂
(當然一些雞毛蒜皮沒什麼特別需要理解就不寫了)
公司幾個厲害的資深同事，在接手對方程式碼時，都得問 ㄟ，你這段共用邏輯在寫什麼
儘管知道func在做什麼，但裡面的邏輯運算在做什麼就得花不少時間理解再拿來應用
時間寶貴，註解只花一點點時間，看別人code難一點的地方沒註解
最後浪費自己時間，也浪費第3、4、5個人來問的時間
最可怕是接手外包開發進來的code沒註解就真的吐血
我是程式註解的信徒，程式要容易被理解的關鍵如下：
總之，註解與程式碼要相輔相成，才能成就大業啦!
去看Clean code那本書吧
答案大師早就講了
簡單的說註解不要重複描述程式碼本身,要寫的是程式碼本身以外的"意圖", "情境"
因為程式碼會因為時間修改, 但註解不影響程式運作, 所以很容易造成註解過時誤導開發者, 但意圖與情境不容易改變.
我寫註解的時候會是類似下面這幾個時間點
一般來說, 以英文程度有一定水準的, 開發稍有心得的, 盡量要求自己不要寫註解, 當你想寫註解的時候, 通常是代表你的程式碼髒了, 需要refactor了, 因為邏輯架構不清楚所以自己才會想寫註解, 去把程式碼改好
而英文程度不好的人, 菜比八, 我個人是建議想寫註解就寫沒關係, 雖然註解有過時詞不達意的問題, 但你英文太差了, 程度太爛了, 本來程式碼就很難懂, 要refactor又做不到, 還他媽自以為高手都不寫, 那會搞慘更多人, 如果覺得自己都快看不懂又沒時間讓你refactor, 那就寫吧!等之後慢慢有點心得的時候在要求自己, 先求有再求好
寫註解這件事,我的看法用"見山是山，見山不是山，見山還是山"來說明
第一階段初入行,見山是山,聽人家說要寫註解,很認真的寫註解,也很認真的讀前輩寫的註解,但還是不能體會寫註解真正意義
第二階段工作一段時間,見山不是山,覺得寫註解沒什麼用,索性就不寫了,別人寫的亂七八糟也不想看
第三階段共同開發的經驗多或當主管了,見山還是山,吃盡了別人/自已註解寫不好,甚至根本就不寫註解的苦,菜鳥又不停的來問問題,這時候您會發現註解的重要,於是您把自己的經驗總結,訂定團隊註解的規範,成為程式開發團隊中的領頭羊~~
所以我的看法是,註解是一定要寫,而且是要有規範的寫!
菜雞+1
一人開發團隊，寫給自己未來嘲笑自己用的......
也可以留下個注腳，哪天發生著作權爭議時，還可以有得查是誰先誰後
多人團隊，我也不想在我離職之後，因後續者無法維護我的程式碼而放棄，重新改寫....
我們公司是遵照 JSDOC 寫
https://jsdoc.app/about-getting-started.html
例如
/**
* Represents a book.
* @constructor
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
function Book(title, author) {
}
你可以很清楚看到一個 function 輸入什麼回傳什麼 而不是逐一解釋
基本上需要逐一解釋的程式碼一定不是好程式碼 XD
也是有同事討論過寫註解得必要性
基本上假如你完全不用寫註解別人也看得懂你在幹嘛
那堪稱完美
註解必要寫應該就是讓人能快速理解快速使用
所以像一些比較難的共用 function 我甚至會提供一些例子讓別人快速使用
iThome鐵人賽
看影片追技術