提升 Python 程式碼可讀性的五個基本技巧

Python 中有許多方法可以幫助我們理解程式碼的內部運作原理，良好的程式設計習慣，可以讓我們的工作事半功倍！

例如，我們最終可能會得到看起來很像下圖中的程式碼。雖然不是最糟糕的，但是，我們需要擴展一些事情，例如：

• load_las_file 函數中的 f 和 d 代表什麼？
• 為什麼我們要在 clay 函數中檢查結果？
• 這些函數需要什麼型別？ Floats? DataFrames?

在本文中，我們將著重討論如何透過文件、提示輸入和正確的變數名稱來提高應用程式/腳本的可讀性的五個基本技巧。

1. Comments

我們可以對我們的程式碼做的第一件事是為我們的程式碼添加某些註釋，但是卻不能過度使用它。註釋應該告訴你為什麼程式碼可以工作或為什麼某事以某種方式完成，而不是它是如何工作的。

Python 中的註解通常使用井號 (#) 來完成，並且可以跨越單行或多行。

# Comment using the hashtag
# Another comment using the hashtag

對於多行註釋，我們也可以使用三個雙引號。

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

在下面的範例中，程式碼中加入了一些註釋，以解釋某些程式碼行背後的工作流程和推理

2. Explicit Typing

Python 語言是動態類型的，這表示變數類型只會在執行時檢查。此外，變數可以在程式碼執行期間更改類型。

另一方面，靜態類型涉及明確說明變數是什麼類型，並且在程式碼執行期間不能更改。

2014 年，PEP 484 引入了類型提示的概念，後來在 Python 3.5 版本中引入，這些允許我們明確說明變數應該是什麼類型。

透過新增類型提示，可以顯著提高程式碼的可讀性。在下面的例子中，我們可以輕鬆得到以下資訊：

##函數需要兩個參數
• 」檔名參數應該是字串型別
• ##start_depth 參數應該是float 類型，預設值為None
• 該函數將傳回一個pandas DataFrame 物件

我們可以立即根據類型提示準確判斷函數需要什麼以及它將返回什麼。

3. Docstrings (Documentation Strings)

文件字串是緊接在函數或類別定義之後的字串文字，Docstrings 是一個很好的方式來詳細解釋我們的函數做什麼，它需要什麼參數，它會引發的任何異常，它會回傳什麼等等。

此外，如果我們使用 Sphinx 之類的工具為程式碼建立線上文檔，則文檔字串將自動被擷取並轉換為適當的文檔。

下面的範例顯示了一個名為 clay_volume 的函數的文件字串。

在這裡，我們可以指定每個參數是什麼，這比基本的類型提示更加詳細，我們還可以包含有關函數背後的方法的更多信息，例如學術參考或方程式。

當我們從程式碼中的其他地方呼叫函數時，擁有文件字串也是非常有幫助的。例如，使用 Visual Studio 編輯程式碼時，可以將滑鼠停留在函數呼叫上，然後查看該函數的功能及其要求的彈出視窗。

如果使用 Visual Studio Code (VSCode) 來編輯我們的 Python 程式碼，可以使用像 autoDocstring 這樣的擴充插件來簡化建立文件字串的過程。該插件允許我們輸入三個雙引號並自動填充模板的其餘部分，我們只需要關注必須填寫的其他詳細資訊。

4. Readable Variable Names

很多時候，當我們寫程式碼時，不會太在意變數的名稱，尤其是當我們急於完成某些功能時。但如果我們的程式碼傳回一系列名為 x1 或 var123 的變量，那麼可能任誰都無法第一眼理解它們所代表的含義。

下面的範例，我們有兩個變數 f 和 d。可以透過查看程式碼的其他部分來猜測這些含義，但這需要一定的時間，尤其是在程式碼很長的情況下。

如果我們為這些變數分配適當的名稱，就能夠知道其中一個是由lasio.read() 呼叫讀取的data_file，並且很可能是原始數據， data 變數告訴我們這是我們正在使用的實際資料。

5. Avoiding Magic Numbers

魔法數字是程式碼中的值，它們背後具有許多無法解釋的含義，可以表示常數。在程式碼中使用這些可能會導致歧義，尤其是對於那些不熟悉其中使用數字的任何計算的人。

此外，如果我們在多個地方有相同的魔法數字並且需要更新它，我們將不得不更新它的每個實例。然而如果將數字分配給正確命名的變量，則整個過程會容易得多。

在下面的範例中，我們有一個函數計算一個名為 result 的值並將其乘以 0.6。透過程式碼我們無法準確的知道該段程式碼的具體意義

如果我們宣告一個變數並將該值分配給它，那麼我們就有更好的機會知道它是什麼。在這種情況下，它是用於將伽馬射線指數轉換為黏土體積的黏土與頁岩的比率。

總結

透過註解和文件字串將文件新增到我們的程式碼中可以大大幫助自己和其他人了解程式碼在做什麼。確實，一開始可能感覺像是一件苦差事，但透過使用工具和定期練習，它可以成為你的第二天性。

以上是提升 Python 程式碼可讀性的五個基本技巧的詳細內容。更多資訊請關注PHP中文網其他相關文章！