第一時間關注土叔的趣文
前幾天，有個同行朋友在我的微信上留言，問我項目代碼裏註釋寫太多會捱打嗎？順手還給我甩了一張截圖，上面密密麻麻的全是手工註釋。
看完之後，我跟她說，挺好的，我已經備好手槍了。
當時我記得跟她開了句玩笑話。玩笑歸玩笑，接下來，馬上進入正題。
「 如何把握這個尺度 」
代碼裏寫註釋，如何才叫多，什麼是多，什麼是少，如何才能把握這個尺度？
還記得老前輩的話猶在耳畔，一份經久不衰的代碼，註釋量與代碼量的比例應該至少爲 2:1。
我很嚴肅地跟她說，寫多了我不知道，寫少了真的可能會被同事槍殺。
從關愛生命的角度出發，土叔送你四個大字：適可而止。
關鍵是要注意一個度。捱打與否，就在一念之間。
說真的，我要是接手一個項目註釋這麼詳細，我會請那個人吃頓飯，而且這個註釋好在是在代碼塊外，如果是代碼中，註釋比代碼還多，影響閱讀代碼那體驗就很糟了。
因此得出一個結論：註釋寫在代碼塊之外，恭喜你，你暫時是安全的。如果是寫在代碼塊內，也要恭喜你，趕緊來我這兒喜提拳擊手套一副。
不過也有在代碼裏玩出花樣的。我司之前有個同事，寫的註釋特別有意思，註釋裏面帶了很多段子，有時候找 BUG 找的心煩，看到他的詭異註釋還是挺不錯的。
「 寫註釋的三個層次 」
寫註釋，有三個層次，土叔總結如下:
1. 什麼代碼都不寫註釋
2. 什麼代碼都寫註釋
3. 只在關鍵處(難理解處 /易出錯處 /易混淆處)寫註釋
前同事也喜歡寫很多註釋, 還要求我也跟他一樣寫,200 行的代碼, 500 行的註釋, 而且註釋跟代碼還不一樣.
註釋裏參數是字符串類型, 代碼裏卻是布爾類型.
所以，此處爲什麼是前同事？因爲代碼不規範，老闆給他放長假了。
「 周圍同事怎麼看 」
對於這個問題，我還特意問了下我司的後端大佬，他回覆我，其他語言我不好說，反正在java裏，如果在方法裏面寫註釋，不單獨拿出一行寫，我絕對會nen死他，哈哈哈哈。
我怕誤導那位朋友，所以又諮詢了我司的前端同事，他跟我說，喜歡這樣的人，除了特別牛的大佬，應該都不會覺得註釋多。唯一比較尷尬的情況是，註釋和代碼版本不同步，代碼是新代碼註釋是舊代碼的註釋，註釋就沒什麼卵用了。
既然前端和後端的小哥哥們都問過了，那就順便再張嘴問下我司的技術負責人吧，聽聽leader是怎麼說的。
我們leader看完截圖後回覆我，這個註釋寫得挺好。把參數來意、方法邏輯在規範的地方寫上了，特別有助於團隊開發。如果是寫過多註釋在方法體內就變成除臭劑了，這樣就不太好了，代碼閱讀起來費勁。不過這一切都是團隊一起規範起來才行，方法體有變更就要即時更新註釋，特別是有些傢伙改了你的東西沒有即時更新，那就TM操蛋了，哈哈。
「 寫註釋究竟是爲了什麼 」
尋其根本，寫註釋是爲了什麼？
對於這個問題，我的答案是：能讓大多數人輕鬆看懂我的代碼，簡而言之就是提高可讀性。
而提高可讀性不一定就要靠儘可能多地寫註釋，甚至不一定要靠註釋，不管你用什麼辦法，只要達到了“能讓大多數人輕鬆看懂我的代碼”的目標就可以了。
註釋越多就越能越輕易看懂嗎？
不一定，像《三傻大鬧寶萊塢》裏主角用了一大串“定義”來描述“書”的時候，教授完全沒聽懂是什麼。
但有的時候算法真的非常複雜，少一點註釋就解釋不清楚，這時候不妨吧代碼拆一拆，分段由淺及深寫註釋，可能效果會更好一些，想象一下如何才能給一個對物理學完全不瞭解的小學生講明白相對論。
當然了，羣裏如果有所謂的技術大佬跟你吹噓，真正好的代碼是不需要註釋的，如果你需要大量註釋來解釋你的代碼，那說明你的代碼還是不夠好。
請記住，這是一句裝逼話，羣裏吹水你也信，你看看Vue.js源碼裏有多少註釋（槓精不要跑過來跟我說，/* 英文的註釋不算 */
）。
Are you sure ?
「 好奇心害死貓 」
文末彩蛋：聊天行將結束之際，那位問我問題的朋友，跟我說，讓土叔見笑了。這幅圖的出處是我寫的代碼。我不但有寫註釋的習慣，還有寫文檔的怪癖。除了這個註釋，我還配了一個上萬字的文檔..........
我頓時驚爲天人。