譯者 | 趙青窕
審校 | 孫淑娟
你是否經(jīng);仡^看看6個(gè)月前寫(xiě)的代碼,想知道這段代碼底是怎么回事?或者從別人手上接手項(xiàng)目,并且不知道從哪里開(kāi)始?這樣的情況對(duì)開(kāi)發(fā)者來(lái)說(shuō)是比較常見(jiàn)的。
Python中有許多方法可以幫助我們理解代碼的內(nèi)部工作方式,因此當(dāng)您從頭來(lái)看代碼或者寫(xiě)代碼時(shí),應(yīng)該會(huì)更容易地從停止的地方繼續(xù)下去。
在此我給大家舉個(gè)例子,我們可能會(huì)得到如下圖所示的代碼。這還不是最糟糕的,但有一些事情需要我們?nèi)ゴ_認(rèn),例如:
在load_las_file函數(shù)中f和d代表什么?
為什么我們要在clay函數(shù)中檢查結(jié)果?
這些函數(shù)需要的是什么類型?浮點(diǎn)數(shù)還是DataFrames?
在load_las_file函數(shù)中f和d代表什么?
為什么我們要在clay函數(shù)中檢查結(jié)果?
這些函數(shù)需要的是什么類型?浮點(diǎn)數(shù)還是DataFrames?
在本文中,我將介紹如何通過(guò)文檔、提示輸入和適當(dāng)?shù)淖兞棵Q來(lái)提高應(yīng)用/腳本的可讀性的5個(gè)基本技巧。
PART 01
注釋
我們可以對(duì)代碼做的第一件事是向某些行添加注釋,但是要注意避免注釋得過(guò)多。注釋中需要闡述代碼為什么能起作用,或者為什么某些事情要以某種方式完成,而不是它是如何實(shí)現(xiàn)的。
Python中的注釋通常使用井號(hào)(#)來(lái)完成,可以跨一行也可以跨多行。
# Comment using the hashtag
# Another comment using the hashtag
對(duì)于多行注釋,我們也可以使用雙引號(hào)。
"""
This is an example of
a multi-line comment
"""
在下面的示例中,代碼中添加了一些注釋,以解釋某些代碼行的工作流程和原因:
PART 02
顯式類型
Python語(yǔ)言是動(dòng)態(tài)類型的,這意味著變量類型只會(huì)在運(yùn)行時(shí)被檢查。此外,變量可以在代碼執(zhí)行期間更改類型。另一方面,靜態(tài)類型涉及顯式地聲明變量類型,并且在代碼執(zhí)行期間不能更改。
2014年,PEP 484引入了類型提示的概念,隨后這個(gè)概念引入到了Python 3.5版本中。這允許您顯式地聲明變量類型。
通過(guò)添加類型提示,可以顯著提高代碼的可讀性。在下面的例子中,我們可以看出:
需要兩個(gè)參數(shù)
參數(shù)filename的類型是字符串
參數(shù)start_depth的類型是float類型,同時(shí)該參數(shù)默認(rèn)值為None
該函數(shù)將返回一個(gè)pandas DataFrame對(duì)象
需要兩個(gè)參數(shù)
參數(shù)filename的類型是字符串
參數(shù)start_depth的類型是float類型,同時(shí)該參數(shù)默認(rèn)值為None
該函數(shù)將返回一個(gè)pandas DataFrame對(duì)象
根據(jù)類型提示,我們可以確切地知道函數(shù)需要什么,以及它將返回什么。
PART 03
文檔字符串
文檔字符串是緊跟在函數(shù)或類定義之后的字符串。文檔字符串是一種很好的方式,可以詳細(xì)解釋函數(shù)的功能、需要什么參數(shù)、將引發(fā)的異常、返回值等等。
此外,如果使用Sphinx之類的工具為代碼創(chuàng)建在線文檔,文檔字符串將自動(dòng)提取并轉(zhuǎn)換為適當(dāng)?shù)奈臋n。
下面的示例顯示了名為clay_volume的函數(shù)對(duì)應(yīng)的文檔字符串。這里我們可以指明每個(gè)參數(shù)的含義。這使它比基本的類型提示更詳細(xì)。您還可以包含更多關(guān)于函數(shù)背后的方法論的信息,如學(xué)術(shù)參考資料或方程。
當(dāng)我們?cè)诖a的其他地方調(diào)用函數(shù)時(shí),文檔字符串也是非常有幫助。例如,使用Visual Studio編寫(xiě)代碼時(shí),可以將鼠標(biāo)懸停在函數(shù)調(diào)用上,然后看到一個(gè)彈出窗口,顯示函數(shù)的功能及其需求。
如果您使用Visual Studio Code (VS Code)編輯您的Python代碼,您可以使用autoDocstring這樣的擴(kuò)展從而使創(chuàng)建文檔字符串的過(guò)程更容易。您可以輸入三個(gè)雙引號(hào),并自動(dòng)填充模板的其余部分。你只需要填上細(xì)節(jié)。
提示:如果您已經(jīng)在參數(shù)中聲明了類型,那么它們將被自動(dòng)選取。
PART 04
具有可讀性的變量名
有時(shí)候,當(dāng)你在寫(xiě)代碼的時(shí)候,你不會(huì)太在意變量的名稱,特別是當(dāng)時(shí)間比較緊張的時(shí)候。但是,如果您返回看代碼時(shí),會(huì)發(fā)現(xiàn)一系列名為x1或var123的變量,您可能無(wú)法一眼理解它們表示什么。
在下面的例子,有兩個(gè)變量f和d。我們可以通過(guò)查看代碼的其他部分來(lái)猜測(cè)這類變量的含義,但這可能會(huì)花費(fèi)時(shí)間,尤其是在代碼很長(zhǎng)的情況下。
如果我們?yōu)檫@些變量指定適當(dāng)?shù)拿Q,我們將能夠知道其中一個(gè)變量是由lasio.read調(diào)用讀取的data_file,并且很可能是原始數(shù)據(jù)。data變量告訴我們這是我們正在處理的實(shí)際數(shù)據(jù)。
PART 05
避免魔法數(shù)字
幻數(shù)是代碼中的值,它們背后有一個(gè)無(wú)法解釋的含義,可以是常量。在代碼中使用這些可能會(huì)導(dǎo)致歧義,尤其是不熟悉計(jì)算中使用數(shù)字的情況。此外,如果我們?cè)诙鄠(gè)地方有相同的神奇數(shù)字,當(dāng)需要更新它,我們必須更新它的每個(gè)實(shí)例。然而,如果給這類數(shù)字分配一個(gè)合適的命名變量,那替換的過(guò)程就會(huì)容易得多。
在下面的例子中,我們有一個(gè)函數(shù),它計(jì)算一個(gè)名為result的值,并將其乘以0.6。這是什么意思?它是一個(gè)轉(zhuǎn)換因子嗎?一個(gè)標(biāo)量嗎?
如果我們聲明一個(gè)變量并將該值賦給它,那么我們就更有可能知道它是什么。在這種情況下,將伽馬射線指數(shù)轉(zhuǎn)換為粘土體積所用的是粘土與頁(yè)巖的比值。
PART 06
最終代碼
在應(yīng)用了上面的技巧之后,我們的最終代碼現(xiàn)在看起來(lái)更清晰,更容易理解。
PART 07
總結(jié)
通過(guò)注釋和文檔字符串向代碼添加說(shuō)明有助于幫助您和其他人理解代碼正在做什么。一開(kāi)始可能會(huì)覺(jué)得這是一件苦差事,但隨著工具的使用和定期的練習(xí),它會(huì)成為你的第二天性。
文章內(nèi)容僅供閱讀,不構(gòu)成投資建議,請(qǐng)謹(jǐn)慎對(duì)待。投資者據(jù)此操作,風(fēng)險(xiǎn)自擔(dān)。
2024年的Adobe MAX 2024發(fā)布會(huì)上,Adobe推出了最新版本的Adobe Creative Cloud。
奧維云網(wǎng)(AVC)推總數(shù)據(jù)顯示,2024年1-9月明火炊具線上零售額94.2億元,同比增加3.1%,其中抖音渠道表現(xiàn)優(yōu)異,同比有14%的漲幅,傳統(tǒng)電商略有下滑,同比降低2.3%。
“以前都要去窗口辦,一套流程下來(lái)都要半個(gè)月了,現(xiàn)在方便多了!”打開(kāi)“重慶公積金”微信小程序,按照提示流程提交相關(guān)材料,僅幾秒鐘,重慶市民曾某的賬戶就打進(jìn)了21600元。
華碩ProArt創(chuàng)藝27 Pro PA279CRV顯示器,憑借其優(yōu)秀的性能配置和精準(zhǔn)的色彩呈現(xiàn)能力,為您的創(chuàng)作工作帶來(lái)實(shí)質(zhì)性的幫助,雙十一期間低至2799元,性價(jià)比很高,簡(jiǎn)直是創(chuàng)作者們的首選。
9月14日,2024全球工業(yè)互聯(lián)網(wǎng)大會(huì)——工業(yè)互聯(lián)網(wǎng)標(biāo)識(shí)解析專題論壇在沈陽(yáng)成功舉辦。