如何看待程序員不寫注釋？

01-07

公司團隊的人幾乎不寫文檔, 也基本不寫注釋(一大段代碼可能就一句話).
邏輯混亂, 又誇多個文件調用函數. 層層嵌套.
一般來說, 自己寫的代碼, 如果不寫注釋的話, 可能過個3天, 自己都不太記得住當時的思路了.更何況是重新維護代碼的人呢?

大家如何看待這個問題? 或者有什麼好的建議?

每一個良好的「編程習慣」背後都有一套協作場景和項目/虛擬資產管理需求為背景。

所以你可以把你們團隊的問題收集起來，有針對性的提出方案，讓別人知道每一個原則是為了解決什麼問題而提出的，這問題在你們團隊有多麼突出。

如果上來就拋出一大堆讓人「不明覺厲」的好習慣出來，反而讓沒經驗的人覺得摸不著頭腦，讓有經驗的人覺得你在照葫蘆畫瓢，而不是在解決問題。

從問題描述得知，問題非在於注釋，而是項目整體質量有問題。

寫注釋如果方法不對，是比沒寫還惡劣的行為！

我想到的，常見的情況有：

1. 注釋不規範或過度注釋

隨意的，到處都是注釋，有用沒用的都寫，比如：

a = 1; // 給 a 賦值為1

誰還看不懂 a=1 是做啥么...

2. 注釋不維護

業務變化比較快的系統，需要連續不斷的開發，你要一直對它做維護性質的開發，有時候要不斷的修改代碼以適應業務的變化。這時候問題就來了。。

比如某個函數一開始是做A這件事，第一個人為這個函數寫了注釋是A，後來業務變化，第二個人把這個函數改成做B這件事了，然後測試通過，沒問題了。此時注釋還是A. 後來第三個人改成了做C，注釋仍然是A。

函數的功能可測，但是注釋不可測，注釋需要人的維護，如果不維護簡直就是噩夢。

假設有第四個人過來讀代碼，看到注釋都是A的內容，他是不是會一頭霧水呢？

有些注釋，有人認為很有用，但我覺得在這種場景下不一定。

比如有人喜歡 @author xxx 在函數或者類的前邊標記自己的大名，我就覺得這個做法在多人、業務變化的開發場景下，很雞肋。通常人家把你的代碼改得面目全非了，看作者還是你，今後出了問題，後來人詛咒的是你這個 author 啊....

3. 代碼只注釋，不刪除

很多人寫代碼總有這種習慣，一段代碼不用了，注釋掉，心裡總想著這段代碼以後可能還會用。但大多數情況下，過幾天就忘了，結果代碼里到處都是「注釋」，沒有一句是有用的。讀代碼的人也不敢刪，一直留著留著。

我還是比較推薦寫文檔不寫注釋的。在看懂代碼之前，當然要有文檔，不然你看那些散落在各個地方的注釋能看懂什麼。文檔之後就是測試用例。測試用例都看完了，你基本不需要注釋了。所以我們只需要在好好寫文檔和測試之後，在那些語法或演算法的奇技淫巧的地方寫注釋就行了。

寫注釋不是一個 systematic 的過程，而是一個 on-demand 過程。在維護過程中，哪裡的 bug 比較多，fix 的方案不太直觀，哪裡就需要寫注釋。或者哪裡的代碼同事之間討論比較多，有語法上不能約束的語義約束，就需要寫注釋。

注釋寫給 data structure，比寫給函數里的代碼要好。但不是絕對的。

如果一個項目，對注釋的要求太 systematic，或者忽視 on-demand 的注釋過程，都是不好的。

你首先要搞清楚寫注釋的目的是什麼。

我對注釋的理解是：注釋是為了能夠讓讀者（代碼完成若干長時間後的自己、新接手這份代碼的同行、協同工作的夥伴、調用你介面的人）清晰地理解每段程序的意圖。

最理想的狀態是程序有自說明功能，不需要額外地寫注釋。

如果要寫注釋：需要遵循一定的原則：具體參見《代碼大全》第32章-自說明代碼；

如果不寫注釋：請先確保你的代碼能夠自說明每一行程序的意圖。

建議：

注釋最好用英文，如果用中文可能會導致在不同的IDE下默認編碼不一致導致亂碼的問題；
如果你是給別人提供介面，最好參照標準注釋以便生成注釋文檔，要是順帶一段demo程序就更好了；
建議在每個函數/方法的注釋裡面，注釋上不同入參對應的相應返回值，類似下面這樣：

以前剛入職時喜歡往代碼里注釋各種顏文字(｀?ω?′)，後來被狠批一頓就老實了(′；ω；`)。

我覺得，如果邏輯清晰，命名規範，如非必要不寫也沒問題，還不如完善好文檔。

如果代碼重構的很好，可以替代一部分注釋。

如果有足夠的單元測試，可以替代一部分注釋。

如果是Java這種冗餘度很高，自解釋能力很強的語言，注釋倒也可以少一點。

如果是C/C++的話建議還是多寫點注釋為好。

代碼即注釋 + 完善文檔就不用寫注釋了

不寫注釋這麼任性的行為，如果不是重劍無鋒，大巧不工，那就一定是SB才會做的行為。

這樣說吧，如果讓我修補一段沒有注釋的代碼，我寧可自己重新寫一遍。（於是在自己讀不懂自己的程序然後重寫了N遍代碼以後終於明白注釋的重要性了。。。）

我覺得Haskell/OCaml之類的語言，把類型簽名都寫出來差不多就是文檔了。。

I heard from someone non-exist

"good code explains itself"

可以理解，不能鼓勵。

跳吧

關於注釋，我最喜歡的建議是《代碼大全》里給出的。

這是個編程風格/習慣的話題，此類話題真心推薦閱讀《代碼大全》

有一部分同學可能堅持：自說明代碼不需要注釋，我其實也蠻喜歡這個觀點的，今天先不說這個啦，這裡只試著回答「如果寫注釋，有什麼好的建議」

其實核心就是使用偽代碼編程，這是一種編程習慣，我已經愛上它了，把偽代碼落實成代碼後，偽代碼同時又成了絕佳的注釋

偽代碼的好處絕不僅僅是注釋（參考《代碼大全》第9章，偽代碼妙用很多），用以注釋只是偽代碼的副產品，儘管是副產品，並不影響這是絕佳的注釋方式，意圖明確之極

要麼方法別超過5行，要麼還是寫注釋

我的原則是只有在代碼不是自解釋的，或者需要寫一些原理上的說明的時候才寫注釋。

注意個人修養就行了，別人你管不了那麼多，那是領導關心的事。

我也不喜歡寫注釋，因為人懶，而且趨向於相信良好的代碼結構下不需要注釋。

而寫注釋的地方，一般是擔心不寫注釋以後自己都看不懂了，更不用說以後維護了。

個人覺得注釋的重要性遠遠及不上說明文檔，而大多數的說明文檔都是一個readme.md就能解決的問題。

所以怎麼看不寫注釋的人？我覺得這是人之常情，但往往有比注釋更好的解決問題的方法。

以我多年跟程序員一起工作的經驗來說，程序員不寫注釋等同於：

拉屎不擦屁股！！！