下面這些觀點(diǎn)都是程序員在教科書(shū)上、在編碼規(guī)范里、在正統(tǒng)的軟件工程流程里流傳開(kāi)來(lái)的，幫助了許多人在程序員啟蒙期間養(yǎng)成了良好的習(xí)慣、原則。對(duì)許多人（包括曾經(jīng)的我）來(lái)說(shuō)，似乎是理所當(dāng)然的。但是隨著閱歷的增長(zhǎng)，視角在變化、看法也在變化，曾經(jīng)的好惡現(xiàn)在都可能大翻身了。

為代碼寫足夠的注釋，讓代碼易于理解

“所有程序員都會(huì)寫自己看得懂的代碼，但只有優(yōu)秀的程序員才寫大家看得懂的代碼。”這話沒(méi)錯(cuò)，但是——

1. 什么才是“大家看得懂”的定義？我有必要讓我的C++代碼對(duì)于一個(gè)月前才明白指針和引用區(qū)別的初學(xué)者簡(jiǎn)單易懂么？
2. 更重要的是，要代碼能夠“看得懂”，主要是靠足夠多的注釋嗎？

我覺(jué)得這兩點(diǎn)都是扯淡。

關(guān)于第1點(diǎn)，造就了一些自我感覺(jué)過(guò)度良好的人，習(xí)慣性地把前人寫的代碼批得體無(wú)完膚。在他們眼中，這段代碼巨爛，那段代碼是屎，更有甚者，在評(píng)審別人代碼的時(shí)候，一樣說(shuō)出這樣的話來(lái)（請(qǐng)參見(jiàn)這篇文章里的“一坨屎型評(píng)審”）。

反對(duì)我的人會(huì)說(shuō)，軟件公司做產(chǎn)品賺錢，它們希望你的代碼讓不熟悉項(xiàng)目的新員工快速閱讀、上手。這確實(shí)是個(gè)矛盾。說(shuō)白了，你寫的代碼要和一個(gè)團(tuán)隊(duì)的能力匹配。在一個(gè)魚(yú)龍混雜的團(tuán)隊(duì)，甚至一個(gè)糟糕的團(tuán)隊(duì)，你寫出的代碼也許很難和大伙兒產(chǎn)生共鳴，他們希望你寫最普通最易懂的代碼，沒(méi)有精巧的設(shè)計(jì)（我指的是，“某一些精巧的設(shè)計(jì)，恰恰是以降低代碼的可維護(hù)性為代價(jià)的”），沒(méi)有語(yǔ)言高級(jí)特性，看著只有順序、循環(huán)、分支判斷的基本代碼。如果大家都是JavaEE的初學(xué)者，那么就從JSP+Servlet開(kāi)始吧，這樣你們才在一個(gè)圈子里，要不然，沒(méi)有人能真正和你一起討論設(shè)計(jì)和代碼的問(wèn)題。

所以許多上進(jìn)的程序員，會(huì)希望在一個(gè)牛人的團(tuán)隊(duì)里工作。這就像足球運(yùn)動(dòng)員一樣，因?yàn)樽闱蚴羌w運(yùn)動(dòng)，一個(gè)足球運(yùn)動(dòng)員能達(dá)到的高度，是和他所在的團(tuán)隊(duì)息息相關(guān)的。在一個(gè)優(yōu)秀的團(tuán)隊(duì)里，大家個(gè)性各有千秋，擅長(zhǎng)領(lǐng)域不甚相同，但是都學(xué)習(xí)迅速，能力不差太遠(yuǎn)，大家閱讀代碼都能夠很快理解和領(lǐng)會(huì)，而且討論問(wèn)題可以用一些程序員才明白的隱喻（比如有人說(shuō)“我覺(jué)得這里應(yīng)該用一個(gè)builder來(lái)實(shí)現(xiàn)”，大家都明白builder指的是什么），氛圍和效率顯而易見(jiàn)。

如果你恰好對(duì)當(dāng)前需要用到的業(yè)務(wù)和技術(shù)特別熟悉，領(lǐng)先團(tuán)隊(duì)里其他人一大截怎么辦？那你就該在做設(shè)計(jì)編碼的時(shí)候先行一步，你是那個(gè)最該去做架構(gòu)設(shè)計(jì)、寫骨架代碼的人，完成一個(gè)架子以后再來(lái)給大家講解，并和大家討論，改進(jìn)現(xiàn)有的設(shè)計(jì)。也就是說(shuō)，你要多做一些更重要的事，而不是和大家一起分析、一起討論，甚至一人負(fù)責(zé)一個(gè)模塊，***的結(jié)果就是大家根本和你討論不到一塊兒去。

關(guān)于第2點(diǎn)，要代碼“看得懂”，是設(shè)計(jì)出來(lái)的，而不是注釋加出來(lái)的。這和產(chǎn)品質(zhì)量一樣，產(chǎn)品質(zhì)量是設(shè)計(jì)出來(lái)的，而不是測(cè)試測(cè)出來(lái)的。注釋的意義在于對(duì)當(dāng)前代碼自解釋做不到的地方進(jìn)行補(bǔ)充。

所以，你的代碼要易于理解，首先要保持簡(jiǎn)潔和清晰，這既包括良好的設(shè)計(jì)，也包括良好的編碼習(xí)慣，也就是說(shuō)，代碼是自解釋的，其次才通過(guò)注釋的補(bǔ)充，讓代碼更易懂。注意，我不是說(shuō)注釋不重要和不必要，而是說(shuō)，注釋應(yīng)該完成它自己的功用，它遠(yuǎn)不能代替代碼本身自我解釋的價(jià)值。

舉一個(gè)簡(jiǎn)單的例子，你可以這樣寫代碼：

/**  
 * 圖表模型  
 */ 
class Chart{  
    /**  
     * 圖表長(zhǎng)度  
     */ 
    private int length;  
 
    /**  
     * 獲取圖表長(zhǎng)度  
     * @return 圖表長(zhǎng)度  
     */ 
    public int getLength(){  
        return this.length;  
    }  
 
    /**  
     * 設(shè)置圖表長(zhǎng)度  
     * @param length 圖表長(zhǎng)度  
     */ 
    public void setLength(int length){  
        this.length = length;  
    }  
} 

好，那么你告訴我，這段代碼和下面這段代碼相比，你獲取了什么更多的有用信息？

class Chart{  
    private int length;  
 
    public int getLength(){  
        return this.length;  
    }  
    public void setLength(int length){  
        this.length = length;  
    }  
} 

我想你懂我的意思，兩段代碼，代碼本身意思已經(jīng)夠明確了，再加上這些無(wú)聊的注釋，只是浪費(fèi)資源、浪費(fèi)生命。很多編程語(yǔ)言，利用語(yǔ)法糖，連簡(jiǎn)單 get、set方法都可以省了（比如Objective C），而加這種注釋的做法卻依然在反軟件、反人類而行。也許你和我一樣，曾經(jīng)為了公司某些扯淡的規(guī)定，為了規(guī)避某些扯淡的代碼靜態(tài)檢查工具（比如 CheckStyle這樣的，甚至自己開(kāi)發(fā)這種無(wú)聊的檢查工具）檢查結(jié)果中的警告信息，加上了（包括IDE自動(dòng)生成）這些毫無(wú)意義的注釋，于是領(lǐng)導(dǎo)看了： “好，沒(méi)有警告信息，代碼質(zhì)量好”。雖然至始都痛恨這樣的做法，但我還是做了，至今后悔。最讓人痛恨自己的事情就是不得不去做那些自己痛恨的事情。

設(shè)計(jì)文檔要詳細(xì)，細(xì)化到方法定義

持這個(gè)觀點(diǎn)的大有人在。對(duì)于這個(gè)觀點(diǎn)我并不是完全反對(duì)，如果你要說(shuō)設(shè)計(jì)文檔需要“詳細(xì)到可以指導(dǎo)編碼”我還能同意，但是我確實(shí)非常不喜歡詳詳細(xì)細(xì)的設(shè)計(jì)文檔。肯定設(shè)計(jì)文檔的價(jià)值這沒(méi)有錯(cuò)，但是過(guò)于詳細(xì)的設(shè)計(jì)文檔撰寫，往往容易造成紙上談兵的窘境。

有人說(shuō)設(shè)計(jì)文檔太過(guò)粗略了做不好設(shè)計(jì)，事實(shí)上，文檔只是呈現(xiàn)設(shè)計(jì)的其中一種形式而已，做得好設(shè)計(jì)的人，可以一邊編碼一邊思考，可能輔助草稿紙上寫寫劃劃，就可以完成優(yōu)秀的軟件；不會(huì)做設(shè)計(jì)的人，設(shè)計(jì)文檔寫多少頁(yè)都沒(méi)用。這讓我想起了今天和同事關(guān)于TDD的討論，會(huì)做設(shè)計(jì)的人，不讓他用TDD也能寫好代碼；不會(huì)做設(shè)計(jì)的人，TDD又有何用？所以讓TDD成為設(shè)計(jì)的主要工具，那就是扯淡。

再一個(gè)，在設(shè)計(jì)文檔中，不可能做完設(shè)計(jì)，不知你是否有這樣的體會(huì)，設(shè)計(jì)文檔思考得再縝密細(xì)致，等落到代碼上的時(shí)候，還會(huì)和開(kāi)始的思考有許多不同，至少有很多細(xì)小的不同。這是因?yàn)樵O(shè)計(jì)思考本身就是貫穿整個(gè)設(shè)計(jì)編碼過(guò)程的，一人只做設(shè)計(jì)、另一人只寫代碼這樣的理想模式是不可能達(dá)成的。

我了解一些對(duì)日外包公司，程序員拿到手的設(shè)計(jì)文檔就是細(xì)化到方法定義了的，如果你有能力有志氣，在中國(guó)***就不要做外包，尤其是對(duì)日外包，這樣的公司拒絕你的一切思考，就是在摧殘人才。

另外一個(gè)原因，是針對(duì)一些闡明“設(shè)計(jì)文檔可以傳承業(yè)務(wù)和技術(shù)知識(shí)”觀點(diǎn)的人，詳細(xì)的設(shè)計(jì)文檔并不能夠傳承什么業(yè)務(wù)和技術(shù)，原因很簡(jiǎn)單，詳細(xì)的文檔初始撰寫成本高，維護(hù)的成本更高。我不相信程序員在修改了代碼邏輯以后，會(huì)去經(jīng)常保持設(shè)計(jì)文檔的同步性。這不合理，只有代碼才是保持***的，其它一切都會(huì)過(guò)時(shí)。而相對(duì)簡(jiǎn)要或粗略的文檔，穩(wěn)定性就要強(qiáng)得多。

讓項(xiàng)目組各個(gè)角色去評(píng)審代碼設(shè)計(jì)

下面我要駁斥的這個(gè)觀點(diǎn)來(lái)源于我的一些經(jīng)歷，也許并不能算是主流觀點(diǎn)。

對(duì)于設(shè)計(jì)文檔的評(píng)審，如果是設(shè)計(jì)原理、實(shí)現(xiàn)原理，正到了程序員才關(guān)心的層面上，如果不寫代碼的測(cè)試跑來(lái)一起討論，這就成了浪費(fèi)時(shí)間、制造矛盾的做法。我經(jīng)歷過(guò)這樣的事情，覺(jué)得很幽默。專職測(cè)試人員的定位各有千秋，許多人經(jīng)驗(yàn)豐富、無(wú)可替代，但是至少，我接觸的測(cè)試人員中，他們幾乎是不閱讀代碼的，也就是說(shuō)，對(duì)于代碼設(shè)計(jì)（注意，是代碼設(shè)計(jì)，不是產(chǎn)品設(shè)計(jì)）的討論，他們不該參與進(jìn)來(lái)。

另外，不要說(shuō)“我?guī)啄昵耙彩菍懘a的”，毛主席都講了，“不了解情況，就沒(méi)有發(fā)言權(quán)”，如果你對(duì)當(dāng)前的代碼實(shí)現(xiàn)不了解，就不要來(lái)礙手礙腳地評(píng)審代碼層面的設(shè)計(jì)了。

我也經(jīng)歷過(guò)這樣的場(chǎng)景，每一個(gè)產(chǎn)品都要組織一些有經(jīng)驗(yàn)的程序員，去給別的產(chǎn)品的代碼挑刺兒。我的看法是，這很難挑出特別有價(jià)值的毛病來(lái)，原因也是一樣的，你對(duì)別的產(chǎn)品業(yè)務(wù)不了解，那么要花大量精力去閱讀代碼，更要去熟悉業(yè)務(wù)，否則只能從代碼層面上摳摳細(xì)節(jié)。

所以，誰(shuí)來(lái)把關(guān)實(shí)現(xiàn)層面的設(shè)計(jì)和代碼的質(zhì)量最卓有成效呢？正是熟悉項(xiàng)目的程序員們，尤其是項(xiàng)目組骨干，或者一起參與設(shè)計(jì)、編碼和測(cè)試的架構(gòu)師（其實(shí)架構(gòu)師還是一名優(yōu)秀的程序員，我從來(lái)不認(rèn)為“只懂業(yè)務(wù)的架構(gòu)師”有什么資格去做軟件架構(gòu)）。

為代碼設(shè)置量化的限制指標(biāo)

統(tǒng)計(jì)指標(biāo)是有價(jià)值的，但是如果設(shè)置這些量化指標(biāo)給程序員套限，則是違背客觀規(guī)律的行為。這一觀點(diǎn)我有必要舉例說(shuō)明一下：

• 測(cè)試代碼覆蓋率不得低于95%（比如工具EMMA）；
• 方法圈復(fù)雜度不能超過(guò)15（你也許知道圈復(fù)雜度的檢查工具SourceMonitor）；
• 單個(gè)類的行數(shù)不能超過(guò)500，單個(gè)方法的行數(shù)不能超過(guò)200；
• 任意兩個(gè)類之間重復(fù)代碼行數(shù)不能超過(guò)10行（你可能知道重復(fù)代碼檢測(cè)工具Simian）；
• ……

這些硬生生限制，都是反軟件、反人類的。你可以說(shuō)圈復(fù)雜度高的方法也許過(guò)于復(fù)雜，你可以說(shuō)重復(fù)比率高的代碼往往可以優(yōu)化，但是這些都只是一個(gè)輔助的指標(biāo)。這些工具都是用來(lái)幫助程序員改善他們的設(shè)計(jì)和代碼質(zhì)量的，如今它們卻被用來(lái)做反程序員的事。

對(duì)于測(cè)試代碼覆蓋率的要求，而且有許許多多公司拿來(lái)作為代碼質(zhì)量衡量的重要指標(biāo)，我認(rèn)為更是駭人聽(tīng)聞。我寫代碼也做單元測(cè)試，但是會(huì)有選擇地寫UT 用例，不會(huì)去追求測(cè)試覆蓋率，而且測(cè)試再全面也不可能保證結(jié)果的絕對(duì)正確，好鋼要用在刀刃上，時(shí)間的投入要換取劃算的回報(bào)，而不是不計(jì)代價(jià)地補(bǔ)充測(cè)試用例。而且，在這里我要說(shuō)的是，保證軟件質(zhì)量的方式有很多，測(cè)試驗(yàn)證的方式也有很多。即便覆蓋率達(dá)到100%，也不能說(shuō)明質(zhì)量高到哪兒去，追求覆蓋率始終太過(guò)功利。另外，有許多代碼本身就沒(méi)有多大被UT測(cè)試的價(jià)值，這也是不容忽視的。

優(yōu)秀的程序員，應(yīng)該難以容忍自己產(chǎn)出糟糕的代碼，也許對(duì)代碼有一點(diǎn)潔癖，對(duì)代碼之美有不懈的追求。對(duì)這樣的軟件的使用動(dòng)機(jī)，也應(yīng)該來(lái)源于程序員，而相關(guān)數(shù)據(jù)的采集，最終一定要為程序員服務(wù)。

今天只是把上面這些觀點(diǎn)做了個(gè)整理，在和別人談起這些的時(shí)候，其實(shí)我覺(jué)得我只是說(shuō)了實(shí)話而已，我的觀點(diǎn)一點(diǎn)都不偏激。我知道很可能你會(huì)有不同看法，這太好不過(guò)了，但是善意地提醒你，請(qǐng)一定仔細(xì)思考一下，不要被公司的精神和文化洗了腦，我們都是程序員，我們最清楚，或許也都經(jīng)歷過(guò)那些針對(duì)程序員、軟件開(kāi)發(fā)荒唐可笑、乃至不可思議的做法。

原文鏈接：http://www.raychase.net/1000