在軟件中隨處可見命名:要給變量、函數(shù)、參數(shù)、類和封包命名,還要給源代碼及源代碼所在目錄命名,甚至還有jar文件、war文件和ear文件命名。
但是,看似簡單的命名,也是讓不少程序員頭疼的問題。有一些小伙伴,在進(jìn)行變量命名的時(shí)候,對于自己熟悉的英文,可能還會(huì)用英文命名一下,如果需要命名的部分不會(huì)用英文表達(dá),或許就直接用拼音了。
有的童鞋一下想不起來怎么命名,直接用拼音直接用aa,bb等這樣沒有任何代表意義的字母來命名,可讀性非常差,可能自己今天寫的,一個(gè)星期后回來再看,也忘記其具體代表的含義了。
因此,許多人在寫代碼之前,總會(huì)在想啊想啊,用什么命名法好呢?對于經(jīng)常在C++、Java、Python等主流語言上切換的強(qiáng)迫癥來說,換個(gè)語言換種命名風(fēng)格簡直不要太混亂。
既然有這么多命名要做,不妨做好它。本期內(nèi)容中,異步君為大家?guī)砹似饌€(gè)好名字應(yīng)遵從的幾條簡單規(guī)則,一起來看看吧
—01—
名副其實(shí)
名副其實(shí)說起來簡單。我們想要強(qiáng)調(diào),這事很嚴(yán)肅。選個(gè)好名字要花時(shí)間,但省下來的時(shí)間比花掉的多。注意命名,而且一旦發(fā)現(xiàn)有更好的名稱,就換掉舊的。這么做,讀你代碼的人(包括你自己)都會(huì)更開心。
變量、函數(shù)或類的名稱應(yīng)該已經(jīng)答復(fù)了所有的大問題。它該告訴你,它為什么會(huì)存在,它做什么事,應(yīng)該怎么用。如果名稱需要注釋來補(bǔ)充,那就不算是名副其實(shí)。
intd;//elapsedtimeindays名稱d什么也沒說明。它沒有引起讀者對時(shí)間消逝的感覺,更別說以日計(jì)了。我們應(yīng)該選擇指明了計(jì)量對象和計(jì)量單位的名稱:
intelapsedTimeInDays;intdaysSinceCreation;intdaysSinceModification;intfileAgeInDays;選擇體現(xiàn)本意的名稱能讓人更容易理解和修改代碼。下列代碼的目的何在?
publicList<int[]>getThem(){List<int[]>list1=newArrayList<int[]>();for(int[]x:theList)if(x[0]==4)list1.add(x);returnlist1;}為什么難以說明上述代碼要做什么事?里面并沒有復(fù)雜的表達(dá)式,空格和縮進(jìn)中規(guī)中矩,只用到三個(gè)變量和兩個(gè)常量,甚至沒有涉及任何其他類或多態(tài)***,只是(或者看起來是)一個(gè)數(shù)組的列表而已。
問題不在于代碼的簡潔度,而在于代碼的模糊度:即上下文在代碼中未被明確體現(xiàn)的程度。上述代碼要求我們了解類似以下問題的答案:
(1)theList中是什么類型的東西?
(2)theList零下標(biāo)條目的意義是什么?
(3)值4的意義是什么?
(4)我怎么使用返回的列表?
問題的答案沒體現(xiàn)在代碼段中,可代碼段就是它們該在的地方。比方說,我們在開發(fā)一種掃雷游戲,我們發(fā)現(xiàn),盤面是名為theList的單元格列表,那就將其名稱改為gameBoard。
盤面上每個(gè)單元格都用一個(gè)簡單數(shù)組表示。我們還發(fā)現(xiàn),零下標(biāo)條目是一種狀態(tài)值,而該種狀態(tài)值為4表示“已標(biāo)記”。只要改為有意義的名稱,代碼就會(huì)得到相當(dāng)程度的改進(jìn):
publicList<int[]>getFlaggedCells(){List<int[]>flaggedCells=newArrayList<int[]>();for(int[]cell:gameBoard)if(cell[STATUS_VALUE]==FLAGGED)flaggedCells.add(cell);returnflaggedCells;}注意,代碼的簡潔性并未被觸及。運(yùn)算符和常量的數(shù)量全然保持不變,嵌套數(shù)量也全然保持不變,但代碼變得明確多了。
還可以更進(jìn)一步,不用int數(shù)組表示單元格,而是另寫一個(gè)類。該類包括一個(gè)名副其實(shí)的函數(shù)(稱為isFlagged),從而掩蓋住那個(gè)魔術(shù)數(shù)[1]。于是得到函數(shù)的新版本:
publicList<Cell>getFlaggedCells(){List<Cell>flaggedCells=newArrayList<Cell>();for(Cellcell:gameBoard)if(cell.isFlagged())flaggedCells.add(cell);returnflaggedCells;}只要簡單改一下名稱,就能輕易知道發(fā)生了什么。這就是選用好名稱的力量。
—02—
避免誤導(dǎo)
程序員必須避免留下掩藏代碼本意的錯(cuò)誤線索。應(yīng)當(dāng)避免使用與本意相悖的詞,例如,hp、aix和sco都不該用作變量名,因?yàn)樗鼈兌际荱nix平臺(tái)或類Unix平臺(tái)的專有名稱。即便你是在編寫三角計(jì)算程序,hp看起來是一個(gè)不錯(cuò)的縮寫[2],但那也可能會(huì)提供錯(cuò)誤信息。
別用accountList來指稱一組賬號(hào),除非它真的是List類型。List一詞對程序員有特殊意義。如果包納賬號(hào)的容器并非真是一個(gè)List,就會(huì)引起錯(cuò)誤的判斷。
所以,用accountGroup或bunchOfAccounts,甚至直接用accounts都會(huì)好一些。
提防使用外形相似度較高的名稱。例如,想?yún)^(qū)分模塊中某處的XYZControllerFor-EfficientHandlingOfStrings和另一處的XYZControllerForEfficientStorage-OfStrings,會(huì)花多長時(shí)間呢?這兩個(gè)詞的外形實(shí)在太相似了。
以同樣的方式拼寫出同樣的概念才是信息。拼寫前后不一致就是誤導(dǎo)。我們很享受現(xiàn)代Java編程環(huán)境的自動(dòng)代碼完成特性。鍵入某個(gè)名稱的前幾個(gè)字母,按一下某個(gè)熱鍵組合(如果有的話),就能得到一列該名稱的可能形式。
假如相似的名稱依字母順序放在一起,且差異很明顯,那就會(huì)相當(dāng)有助益,因?yàn)槌绦騿T多半會(huì)壓根不看你的詳細(xì)注釋,甚至不看該類的***列表就直接看名字挑一個(gè)對象。
誤導(dǎo)性名稱真正可怕的例子,是用小寫字母l和大寫字母O作為變量名,尤其是在組合使用的時(shí)候。當(dāng)然,問題在于它們看起來完全像是常量“壹”和“零”。
inta=l;if(O==l)a=O1;elsel=01;讀者可能會(huì)認(rèn)為這純屬虛構(gòu),但我們確曾見過充斥這類名稱的代碼。有一次,代碼作者建議用不同字體寫變量名,好顯得更清楚些,但前提是這種方案得要通過口頭和書面?zhèn)鬟f給未來所有的開發(fā)者才行。后來,只是做了簡單的重命名操作,就解決了問題,而且也沒引起別的問題。
—03—
做有意義的區(qū)分
如果程序員只是為滿足編譯器或解釋器的需要而寫代碼,就會(huì)制造麻煩。例如,因?yàn)橥蛔饔梅秶鷥?nèi)兩樣不同的東西不能重名,你可能會(huì)隨手改掉其中一個(gè)的名稱,有時(shí)干脆以錯(cuò)誤的拼寫充數(shù),結(jié)果就會(huì)出現(xiàn)在更正拼寫錯(cuò)誤后導(dǎo)致編譯器出錯(cuò)的情況。
光是添加數(shù)字系列或是廢話遠(yuǎn)遠(yuǎn)不夠,即便這足以讓編譯器滿意。如果名稱必須相異,那么其意思也應(yīng)該不同才對。
以數(shù)字系列命名(a1、a2…aN)是依義命名的對立面。這樣的名稱純屬誤導(dǎo)——完全沒有提供正確信息,沒有提供導(dǎo)向作者意圖的線索。試看:
publicstaticvoidcopyChars(chara1[],chara2[]){for(inti=0;i<a1.length;i++){a2[i]=a1[i];}}如果參數(shù)名改為source和destination,這個(gè)函數(shù)就會(huì)像樣許多。
廢話是另一種沒意義的區(qū)分。假設(shè)你有一個(gè)Product類,如果還有一個(gè)名為ProductInfo或ProductData的類,那它們的名稱雖然不同,意思卻無區(qū)別。Info和Data就像a、an和the一樣,是意義含混的廢話。
注意,只要體現(xiàn)出有意義的區(qū)分,使用a和the這樣的前綴就沒錯(cuò)。例如,你可能把a(bǔ)用在域內(nèi)變量,而把the用于函數(shù)參數(shù)[5]。但如果你已經(jīng)有一個(gè)名為zork的變量,又想調(diào)用一個(gè)名為theZork的變量,麻煩就來了。
廢話都是冗余。variable一詞永遠(yuǎn)不應(yīng)當(dāng)出現(xiàn)在變量名中。table一詞永遠(yuǎn)不應(yīng)當(dāng)出現(xiàn)在表名中。NameString會(huì)比Name好嗎?難道Name會(huì)是一個(gè)浮點(diǎn)數(shù)?如果是這樣,就違反了關(guān)于誤導(dǎo)的規(guī)則。
設(shè)想有一個(gè)名為Customer的類,還有一個(gè)名為CustomerObject的類,它們的區(qū)別何在呢?哪一個(gè)是表示客戶歷史支付情況的最佳方式?
有一個(gè)應(yīng)用反映了這種狀況。為當(dāng)事者諱,我們改了一下,不過犯錯(cuò)的代碼的確就是這個(gè)樣子:
getActiveAccount();getActiveAccounts();getActiveAccountInfo();程序員怎么知道該調(diào)用哪個(gè)函數(shù)呢?
如果缺少明確約定,那么變量moneyAmount與money就沒區(qū)別,customerInfo與customer沒區(qū)別,accountData與account沒區(qū)別,theMessage也與message沒區(qū)別。要區(qū)分名稱,就要以讀者能鑒別不同之處的方式來區(qū)分。
—04—
使用讀得出來的名稱
人類長于記憶和使用單詞。大腦的相當(dāng)一部分就是用來容納和處理單詞的。單詞能讀得出來。人類的大腦中有那么大的一塊地方用來處理言語,若不善加利用,實(shí)在是種恥辱。
如果名稱讀不出來,討論的時(shí)候就會(huì)像個(gè)傻鳥。“哎,這兒,鼻涕阿三喜摁踢(beeceearrthreeceeenntee)[6]上頭,有個(gè)皮挨死極翹(peeesszeekyew)[7]整數(shù),看見沒?”這不是小事,因?yàn)榫幊瘫揪褪且环N社會(huì)活動(dòng)。
有一家公司,程序里面寫了一個(gè)genymdhms(生成日期,年、月、日、時(shí)、分、秒),他們一般讀作“genwhyemmdeeaichemmess”[8]。我有見字照拼讀的惡習(xí),于是開口就念“gen-yah-mudda-hims”。
后來好些設(shè)計(jì)師和分析師都有樣學(xué)樣,聽起來傻乎乎的。我們知道典故,所以會(huì)覺得很搞笑。搞笑歸搞笑,實(shí)際是在強(qiáng)忍糟糕的命名。在給新開發(fā)者解釋變量名的意義時(shí),他們總是讀出傻乎乎的自造詞,而非恰當(dāng)?shù)挠⒄Z詞。比較
classDtaRcrd102{privateDategenymdhms;privateDatemodymdhms;privatefinalStringpszqint="102";/*...*/};和classCustomer{privateDategenerationTimestamp;privateDatemodificationTimestamp;privatefinalStringrecordId="102";/*...*/};現(xiàn)在讀起來就像人話了:“喂,Mikey,看看這條記錄!生成時(shí)間戳(generationtimestamp)[9]被設(shè)置為明天了!不能這樣吧?”
—05—
使用可搜索的名稱
對于單字母名稱和數(shù)字常量,有一個(gè)問題,就是很難在一大篇文字中找出來。
找MAX_CLASSES_PER_STUDENT很容易,但想找數(shù)字7就麻煩了,它可能是某些文件名或其他常量定義的一部分,出現(xiàn)在因不同意圖而采用的各種表達(dá)式中。如果該常量是個(gè)長數(shù)字,又被人錯(cuò)改過,就會(huì)逃過搜索,從而造成錯(cuò)誤。
同樣,e也不是一個(gè)便于搜索的好變量名,它是英文中最常用的字母,在每個(gè)程序、每段代碼中都有可能出現(xiàn)。由此而見,長名稱勝于短名稱,搜得到的名稱勝于用自造編碼代寫就的名稱。
竊以為單字母名稱僅用于短***中的本地變量。名稱長短應(yīng)與其作用域大小相對應(yīng)[N5]。若變量或常量可能在代碼中多處使用,則應(yīng)賦予其便于搜索的名稱。再比較:
for(intj=0;j<34;j++){s+=(t[j]*4)/5;}和intrealDaysPerIdealDay=4;constintWORK_DAYS_PER_WEEK=5;intsum=0;for(intj=0;j<NUMBER_OF_TASKS;j++){intrealTaskDays=taskEstimate[j]*realDaysPerIdealDay;intrealTaskWeeks=(realTaskdays/WORK_DAYS_PER_WEEK);sum+=realTaskWeeks;}注意,上面代碼中的sum并非特別有用的名稱,不過至少搜得到它。采用能表達(dá)意圖的名稱,貌似拉長了函數(shù)代碼,但要想想看,WORK_DAYS_PER_WEEK比數(shù)字5好找得多,而列表中也只剩下了體現(xiàn)作者意圖的名稱。
—06—
避免使用編碼
編碼已經(jīng)太多,無謂再自找麻煩。把類型或作用域編進(jìn)名稱里面,徒然增加了解碼的負(fù)擔(dān)。沒理由要求每位新人都在弄清要應(yīng)付的代碼之外(那算是正常的),還要再搞懂另一種編碼“語言”。這對解決問題而言,純屬多余的負(fù)擔(dān)。帶編碼的名稱通常也不便發(fā)音,容易打錯(cuò)。
匈牙利語標(biāo)記法
在往昔名稱長短很重要的時(shí)代,我們毫無必要地破壞了不編碼的規(guī)矩,如今后悔不迭。Fortran語言要求首字母體現(xiàn)出類型,導(dǎo)致了編碼的產(chǎn)生。BASIC語言的早期版本只允許使用一個(gè)字母再加上一位數(shù)字。匈牙利語標(biāo)記法[10](HungarianNotation,HN)將這種態(tài)勢愈演愈烈。
在Windows的C語言API的時(shí)代,HN相當(dāng)重要,那時(shí)所有名稱要么是一個(gè)整數(shù)句柄,要么是一個(gè)長指針或者void指針,要不然就是string的幾種實(shí)現(xiàn)(有不同的用途和屬性)之一。那時(shí)候編譯器并不做類型檢查,程序員需要匈牙利語標(biāo)記法來幫助自己記住類型。
現(xiàn)代編程語言具有更豐富的類型系統(tǒng),編譯器也記得并強(qiáng)制使用類型。而且,程序員趨向于使用更小的類、更短的***,好讓每個(gè)變量的定義都在視野范圍之內(nèi)。
Java程序員不需要類型編碼,因?yàn)閷ο笫菑?qiáng)類型的,代碼編輯環(huán)境已經(jīng)先進(jìn)到在編譯開始前就能監(jiān)測到類型錯(cuò)誤的程度!所以,如今HN和其他的類型編碼形式都純屬多余。它們增加了修改變量、函數(shù)或類的名稱或類型的難度,它們增加了閱讀代碼的難度,它們制造了讓編碼系統(tǒng)誤導(dǎo)讀者的可能性。
PhoneNumberphoneString;//namenotchangedwhentypechanged!成員前綴
也不必用m_前綴來標(biāo)明成員變量。應(yīng)當(dāng)把類和函數(shù)做得足夠小,以消除對成員前綴的需要。你應(yīng)當(dāng)使用某種可以高亮或用顏色標(biāo)出成員的編輯環(huán)境。
publicclassPart{privateStringm_dsc;//ThetextualdescriptionvoidsetName(Stringname){m_dsc=name;}}--------------------------------------------------------------------------------------publicclassPart{Stringdescription;voidsetDescription(Stringdescription){this.description=description;}}此外,人們會(huì)很快學(xué)會(huì)無視前綴(或后綴),而只看到名稱中有意義的部分。代碼讀得越多,眼中就越?jīng)]有前綴。最終,前綴變作了不入法眼的廢料,變作了舊代碼的標(biāo)志物。
接口和實(shí)現(xiàn)
有時(shí)也會(huì)出現(xiàn)采用編碼的特殊情形。比如,你在做一個(gè)創(chuàng)建形狀用的抽象工廠(AbstractFactory),該工廠是一個(gè)接口,要用具體類來實(shí)現(xiàn)。你怎么來命名工廠和具體類呢?IShapeFactory和ShapeFactory嗎?我喜歡不加修飾的接口。前導(dǎo)字母I被濫用到了說好聽點(diǎn)兒是干擾,說難聽點(diǎn)兒根本就是廢話的程度。
我不想讓用戶知道我給他們的是接口,而就想讓他們知道那是一個(gè)ShapeFactory。如果在接口和實(shí)現(xiàn)中必須選其一來編碼的話,我寧肯選擇實(shí)現(xiàn)。ShapeFactoryImp,甚至是丑陋的CShapeFactory,都比對接口名稱編碼好。
-END-
代碼整潔之道
作者:[美]羅伯特·C.馬丁(RobertC.Martin)
譯者:韓磊
內(nèi)容簡介:
軟件質(zhì)量,不但依賴架構(gòu)及項(xiàng)目管理,而且與代碼質(zhì)量緊密相關(guān)。這一點(diǎn),無論是敏捷開發(fā)流派還是傳統(tǒng)開發(fā)流派,都不得不承認(rèn)。
本書提出一種觀點(diǎn):代碼質(zhì)量與其整潔度成正比。干凈的代碼,既在質(zhì)量上較為可靠,也為后期維護(hù)、升級(jí)奠定了良好基礎(chǔ)。作為編程領(lǐng)域的佼佼者,本書作者給出了一系列行之有效的整潔代碼操作實(shí)踐。這些實(shí)踐在本書中體現(xiàn)為一條條規(guī)則(或稱“啟示”),并輔以來自實(shí)際項(xiàng)目的正、反兩面的范例。只要遵循這些規(guī)則,就能編寫出干凈的代碼,從而有效提升代碼質(zhì)量。
本書閱讀對象為一切有志于改善代碼質(zhì)量的程序員及技術(shù)經(jīng)理。書中介紹的規(guī)則均來自作者多年的實(shí)踐經(jīng)驗(yàn),涵蓋從命名到重構(gòu)的多個(gè)編程方面,雖為一“家”之言,然誠有可資借鑒的價(jià)值。