? ? ? ? 只要寫代碼，就會遇到代碼注釋的問題。在不同的公司，不同的項目組，不同的項目中，可能會有不同的注釋標準。有些標準讓我們感覺很受益，有些則讓我們感覺很反感。而對于沒有明確標準的項目，我們往往會遇到“百花齊放，百家爭鳴”般的注釋。我無法給出一個明確的標準，只是在此探討下：什么樣的注釋不應(yīng)該寫，什么地方需要寫注釋。（轉(zhuǎn)載請指明出于breaksoftware的csdn博客）

“不”的原則

不是每行代碼都需要寫注釋

? ? ? ? 這個原則源于之前我和同事的一個爭論。當時我們討論代碼注釋該怎么寫的問題，最終同事拋出這么一個觀點：“我之前在X為干過，那兒就需要每行代碼都寫注釋，所以我們應(yīng)該執(zhí)行這樣的標準”。想必大家都可以猜到那是一家什么公司，但是從我個人角度分析，同事之前可能去的是一家假的“X為”公司。因為我覺得那個公司不應(yīng)該如此沒有技術(shù)品味吧？

? ? ? ? 之后的探討，我們將以畫作為例。因為畫是一種藝術(shù)表達，而我們的代碼也應(yīng)該寫的和藝術(shù)品一樣，表達出一種美。下圖是梵高的《向日葵》原作，圖中只有若干向日葵花、花瓶、地面（或者說是承載體）等元素。

? ? ? ? 假如我們對這份“代碼”每行加一個注釋，則呈現(xiàn)如下

? ? ? ? 各位看官感覺如何？我覺得如果梵高畫的如果不像向日葵的話，這樣搞點“注釋”可能還有存在的意義。但是如果作品足夠表意，那么再加上注釋就是畫蛇添足。這種為寫注釋而寫注釋是非常不可取的。為什么呢？因為

?

• 增加編碼人員無價值的工作量
• 讓編碼人員降低對自己代碼質(zhì)量的要求，因為“反正要寫注釋”，叫index還是叫xpoesiejd無所謂。
• 讓對自己編碼有藝術(shù)美感的編碼人員產(chǎn)生抵觸。比如我們要是讓梵高給他原作加上上圖一樣的注釋，我想梵高可能早就不想活了。

? ? ? ? 但是我相信我同事可能說的是“真”的，但是這個“真”被我打了一個引號。因為我懷疑他之前可能在一家給X為干活的外包公司工作。也許X為的確有嚴格的代碼注釋量要求（也許“注釋行數(shù)”/“代碼行數(shù)”>0.5），于是這家外包公司就做了一個“任何一行代碼都要寫注釋”的要求。我想如果他們真的這么去執(zhí)行了，代碼的注釋量的確是上去了，但是或許注釋的質(zhì)量降低了，或者工作效率降低了。

不要寫廢話

? ? ? ? 上圖是歐仁·德拉克羅瓦的著名油畫《自由引導人民》。這幅作品是為了法國七月革命而作，最前方的那個女性是克拉拉·萊辛，象征著自由女神。她左手邊男孩象征著阿萊爾，右手邊戴大禮帽的男性象征著資產(chǎn)階級，貝雷帽男性則象征著工人。可以見得這幅畫包含了大量的背景知識。但是如果我們用廢話注釋它就是

? ? ? ? 是不是要抓狂？對于這樣顯而易見的信息寫注釋就是“廢話”！

不要寫錯誤的注釋

? ? ? ? 上圖是徐悲鴻的著名油畫《田橫五百士》。我們拋開這幅畫的時代意義，單從歷史畫角度來看，大師給我們傳達了一個錯誤的信息——人物的著裝不符合故事地域年代（秦末齊國地區(qū)）。如果該幅畫沒有留下名字，后人通過畫作的衣著信息（可以看成是一種注釋）對該畫所表達的故事進行推理時，可能出現(xiàn)斷代錯誤，從而得出的故事和作者想表達的不同。

不要亂留名

? ? ? ??

? ? ? ? 這幅是元代趙孟頫的《水村圖卷》。請注意一下右上角那個大大的、紅紅的、方方正正的印章——乾隆御筆之寶。可能你會覺得乾隆爺給這幅畫加蓋了自己的印章，會導致該幅畫價值大大增加，但是實際效果是恰恰相反。乾隆爺是有名的毀畫大師，他經(jīng)常在一些有名的作品上胡亂加蓋自己的印章——留名。于是這些畫作經(jīng)他這么一折騰就會貶值。連乾隆爺?shù)拿侄寄敲床恢靛X，我們何必要在代碼中亂留名呢？

? ? ? ? 但是如果這份文件是你編寫的，你還是要在版權(quán)信息中寫入你的名字。這就和中國古人畫作一般都會自己簽名和蓋自己印章一樣。

? ? ? ? 可能你會辯解，說：我添加的這段邏輯非常重要，我要留名以便以后有人能找到我。我覺得這個問題應(yīng)該這么看：如果你的代碼重要程度可以顛覆原作，我覺得你可以考慮重寫一份并署上自己名字；如果沒那么重要還是把留名交給原作者吧，畢竟你的成果是在他基礎(chǔ)之上獲得呢。

不要注釋掉代碼

? ? ? ? 我想這個問題是最最常見的。大家翻翻自己項目的代碼，可能都會遇到這種現(xiàn)象。當我們不需要一段代碼時，可能也會估計是“永遠不用了”還是“暫時不用了”。于是很多人對“暫時不用了”的代碼使用注釋方式使其無效。但是一般來說，這種“暫時不用了”的代碼很有可能就是“永遠不用了”，而人們已經(jīng)忘記要去刪除它了。這個現(xiàn)象在實際項目中比比皆是。所以個人覺得：不要的代碼要果斷刪除。即使以后真的要用了，我們可以使用代碼管理工具（svn或者git）方便的找回。

? ? ? ? 下圖是庫爾貝的油畫《受傷的男人》。其實作者在呈現(xiàn)這幅畫之前，畫布上畫了一個女性頭部。可能作者覺得這塊邏輯可能沒用了，于是就用黑色把“她”抹去，從而也成就了這幅名畫。假想作者如果使用“注釋”的手段將這顆頭顱保留在畫作中，將是如何嚇人的一幅場景。

不要寫小故事

? ? ? ? 在工作中，可能某個類的設(shè)計思路來源于和產(chǎn)品經(jīng)理或者技術(shù)經(jīng)理的思想碰撞，可能這個過程很精彩，有些編碼者就將整個故事用注釋的方式放在代碼中。也有可能這個類和歷史上一個著名人物有關(guān)，比如我們要編寫斐波拉契數(shù)列實現(xiàn)，就將斐波拉契平生故事放到代碼里。我覺得這些內(nèi)容放在代碼中是非常不合適的，也許你覺得很精彩，但是別人很有可能不關(guān)心啊。

? ? ? ? 比如下圖是米開朗琪羅的《耶穌受難》

? ? ? ? 現(xiàn)在我們覺得耶穌受難前“最后的晚餐”故事很精彩，于是我們把這段《新約圣經(jīng)》“注釋”到畫作中

? ? ? ? 米開朗琪羅如果這么作畫，可能現(xiàn)在我對他的認知中少了“畫家”這一項。

不要有宗教傾向

? ? ? ? 這個問題在國內(nèi)不算太大的問題。因為程序員大部分是無神論者。當我們看到“佛祖保佑”或者“God save me”是往往是莞爾一笑。但是我們不能假設(shè)以后閱讀這份代碼的人沒有宗教信仰，也許他信奉的和你正好相反呢。代碼是沒有宗教的，編碼者是有的。

? ? ? ? 我們比較常見是的“佛祖保佑 永無bug”

? ? ? ? 個人比較反感這種做法。所以我會在自己的項目中，將這種注釋都刪掉。假如我們的代碼要依靠神來保佑，我只能質(zhì)疑你代碼的質(zhì)量是不是已經(jīng)超神了。我們還是要信奉二進制的。

不要博人一笑

? ? ? ? 代碼是嚴謹?shù)倪壿嫳磉_，不要寫一些逗人開心的內(nèi)容。可能上例中“佛祖保佑，永無bug”在一些編碼者看來只是為了博人一笑。但是我覺得閱讀代碼是一件需要連續(xù)動腦筋的事，如果我們閱讀過程被這些“笑話”不停打斷，那么最終的理解效率得有多低？

? ? ? ? 比如著名的《清明上河圖》，它包含了大量的社會信息。假如我每隔一段注釋一個笑臉，那么這幅畫可能就沒那么高的藝術(shù)價值了。

不要批判前人

? ? ? ? 寫出完美的代碼的確是非常稀少的。所以我們閱讀別人代碼時，往往可以發(fā)現(xiàn)很多問題。在感覺不爽時，可能心中默默鄙視一下作者；再不爽時，可能和同事數(shù)落一下作者；再再不爽時，可能就要在代碼中批判一下作者。但是這種注釋對代碼是有意義的么？而且并不是我們總是對的。由于對問題的理解深度、角度不同，編碼者就是可能會寫出讓你不滿意但是符合他自己原則的代碼。

? ? ? ? 比如梵高的《星空》

? ? ? ? 像我這種鑒賞能力比較差的，的確很難說出他畫的哪兒好了。假如我給這幅畫做了如下注釋

? ? ? ? 我想我并不會獲得別人的贊許，可能全是對我的鄙視。那怎么辦？我覺得我應(yīng)該去畫一幅符合我心目中“星空”的油畫，這樣供其他人在我和梵高中做個選擇。或許這是一種自不量力，但是這卻是一種對原作者的尊重。

“要”的原則

? ? ? ? 說了這么多“不”的原則，其實我知道我還是沒有說全。但是我們換個角度，如果我們知道“要”的原則，然后對其取反，就是涵蓋所有“不”的原則了。

? ? ? ? 在討論這個話題之前，我先說下我對代碼和注釋的認識。

? ? ? ? 首先我認為代碼要寫的和注釋一樣表意。也就是說我們要窮盡自己的思想，努力掌控每個名詞、每個動詞、每個換行、每個空格、每個組織形式以達到讓代碼可以自說明邏輯及業(yè)務(wù)。

? ? ? ? 其次代碼和注釋應(yīng)該是一個整體。往往一份文件包含代碼和注釋兩部分，而閱讀這份文件也有兩個主體——編譯器和人。編譯器只是通過代碼來獲得邏輯信息，而人的要通過代碼和注釋一起理解邏輯和業(yè)務(wù)。

? ? ? ? 基于第二點，我認為一份文件最好只有一個故事線——只需要用代碼去表達，因為它是人和編譯器同時可以去理解的。如果一個故事經(jīng)過兩個人去講述，隨著時間推移，最終會變成兩個故事。這是非常可怕的。

? ? ? ? 所以我的觀點是：如果代碼足夠表意，且不違背常理，不應(yīng)該去添加注釋。反之則需要加注釋。

? ? ? ? 但是現(xiàn)實社會中，有時候很難做到不違背常理。因為我們這個世界隨機性太強，有時候我們就要放棄一些我們認識的“常理”去達到期望的目的。這個時候我們代碼的表達能力可能就是不足的了，就需要注釋來表達。

? ? ? ? 比如齊白石的畫作中，壽桃往往是用來祝壽的

? ? ? ? 這個常理我們中國人都可以理解。但是假如我們看到下面這幅畫，你覺得他是齊白石用來干嘛的？

? ? ? ? 它其實也是用于祝壽的。它是齊白石向蔣公祝60大壽時送的，和這幅畫一起送的還有一副對聯(lián)——人生長壽，天下太平。完整的版本是

? ? ? ? 假如覺得這副對聯(lián)還不夠表達“潛臺詞”，則上聯(lián)左上側(cè)“主席壽”幾個字則可以完全說明了吧。

? ? ? ? 這幅《松柏高立圖》在2011年以4.255億被拍賣，而它則是我認為需要寫“注釋”的一個典型代表。

總結(jié)

以上是生活随笔為你收集整理的谈代码注释的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。