Python 中有許多方法可以幫助我們理解代碼的內(nèi)部工作原理，良好的編程習(xí)慣，可以使我們的工作事半功倍！

例如，我們最終可能會(huì)得到看起來(lái)很像下圖中的代碼。雖然不是最糟糕的，但是，我們需要擴(kuò)展一些事情，例如：

• load_las_file 函數(shù)中的 f 和 d 代表什么？
• 為什么我們要在 clay 函數(shù)中檢查結(jié)果？
• 這些函數(shù)需要什么類型？Floats? DataFrames?

在本文中，我們將著重討論如何通過(guò)文檔、提示輸入和正確的變量名稱來(lái)提高應(yīng)用程序/腳本的可讀性的五個(gè)基本技巧。

1. Comments

我們可以對(duì)我們的代碼做的第一件事是為我們的代碼添加某些注釋，但是卻不能過(guò)度使用它。注釋應(yīng)該告訴你為什么代碼可以工作或者為什么某事以某種方式完成，而不是它是如何工作的。

Python 中的注釋通常使用井號(hào) (#) 來(lái)完成，并且可以跨越單行或多行。

# Comment using the hashtag
# Another comment using the hashtag

對(duì)于多行注釋，我們也可以使用三個(gè)雙引號(hào)。

"""
This is an example of
a multi-line comment
"""

在下面的示例中，代碼中添加了一些注釋，以解釋某些代碼行背后的工作流程和推理

2. Explicit Typing

Python 語(yǔ)言是動(dòng)態(tài)類型的，這意味著變量類型只會(huì)在運(yùn)行時(shí)檢查。此外，變量可以在代碼執(zhí)行期間更改類型。

另一方面，靜態(tài)類型涉及明確說(shuō)明變量是什么類型，并且在代碼執(zhí)行期間不能更改。

2014 年，PEP 484 引入了類型提示的概念，后來(lái)在 Python 3.5 版本中引入，這些允許我們明確說(shuō)明變量應(yīng)該是什么類型。

通過(guò)添加類型提示，可以顯著提高代碼的可讀性。在下面的例子中，我們可以輕松得到如下信息：

• 函數(shù)需要兩個(gè)參數(shù)
• 文件名參數(shù)應(yīng)該是字符串類型
• start_depth 參數(shù)應(yīng)該是 float 類型，默認(rèn)值為 None
• 該函數(shù)將返回一個(gè) pandas DataFrame 對(duì)象

我們可以立即根據(jù)類型提示準(zhǔn)確判斷函數(shù)需要什么以及它將返回什么。

3. Docstrings (Documentation Strings)

文檔字符串是緊跟在函數(shù)或類定義之后的字符串文字，Docstrings 是一個(gè)很好的方式來(lái)詳細(xì)解釋我們的函數(shù)做什么，它需要什么參數(shù)，它會(huì)引發(fā)的任何異常，它會(huì)返回什么等等。

此外，如果我們使用 Sphinx 之類的工具為代碼創(chuàng)建在線文檔，則文檔字符串將自動(dòng)被拾取并轉(zhuǎn)換為適當(dāng)?shù)奈臋n。

下面的示例顯示了一個(gè)名為 clay_volume 的函數(shù)的文檔字符串。

在這里，我們可以指定每個(gè)參數(shù)是什么，這比基本的類型提示更加詳細(xì)，我們還可以包含有關(guān)函數(shù)背后的方法的更多信息，例如學(xué)術(shù)參考或方程式。

當(dāng)我們從代碼中的其他地方調(diào)用函數(shù)時(shí)，擁有文檔字符串也是非常有幫助的。例如，使用 Visual Studio 編輯代碼時(shí)，可以將鼠標(biāo)懸停在函數(shù)調(diào)用上，然后查看該函數(shù)的功能及其要求的彈出窗口。

如果使用 Visual Studio Code (VSCode) 來(lái)編輯我們的 Python 代碼，可以使用像 autoDocstring 這樣的擴(kuò)展插件來(lái)簡(jiǎn)化創(chuàng)建文檔字符串的過(guò)程。該插件允許我們輸入三個(gè)雙引號(hào)并自動(dòng)填充模板的其余部分，我們只需要關(guān)注必須填寫的其他詳細(xì)信息即可。

4. Readable Variable Names

很多時(shí)候，當(dāng)我們編寫代碼時(shí)，不會(huì)太在意變量的名稱，尤其是當(dāng)我們急于完成某些功能時(shí)。但是如果我們的代碼返回一系列名為 x1 或 var123 的變量，那么可能任誰(shuí)都無(wú)法第一眼理解它們所代表的含義。

下面的示例，我們有兩個(gè)變量 f 和 d?？梢酝ㄟ^(guò)查看代碼的其他部分來(lái)猜測(cè)這些含義，但這需要一定的時(shí)間，尤其是在代碼很長(zhǎng)的情況下。

如果我們?yōu)檫@些變量分配適當(dāng)?shù)拿Q，就能夠知道其中一個(gè)是由 lasio.read() 調(diào)用讀取的 data_file，并且很可能是原始數(shù)據(jù)，data 變量告訴我們這是我們正在使用的實(shí)際數(shù)據(jù)。

5. Avoiding Magic Numbers

魔法數(shù)字是代碼中的值，它們背后具有很多無(wú)法解釋的含義，并且可以表示常量。在代碼中使用這些可能會(huì)導(dǎo)致歧義，尤其是對(duì)于那些不熟悉其中使用數(shù)字的任何計(jì)算的人。

此外，如果我們?cè)诙鄠€(gè)地方有相同的魔法數(shù)字并且需要更新它，我們將不得不更新它的每個(gè)實(shí)例。然而如果將數(shù)字分配給正確命名的變量，則整個(gè)過(guò)程會(huì)容易得多。

在下面的示例中，我們有一個(gè)函數(shù)計(jì)算一個(gè)名為 result 的值并將其乘以 0.6。通過(guò)代碼我們無(wú)法準(zhǔn)確的知道該段代碼的具體含義

如果我們聲明一個(gè)變量并將該值分配給它，那么我們就有更好的機(jī)會(huì)知道它是什么。在這種情況下，它是用于將伽馬射線指數(shù)轉(zhuǎn)換為粘土體積的粘土與頁(yè)巖的比率。

總結(jié)

通過(guò)注釋和文檔字符串將文檔添加到我們的代碼中可以大大幫助自己和其他人了解代碼在做什么。確實(shí)，一開(kāi)始可能感覺(jué)像是一件苦差事，但通過(guò)使用工具和定期練習(xí)，它可以成為你的第二天性。