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

譯者| 趙青窕

審校| 孫淑娟

你是否經常回頭看看6個月前寫的程式碼，想知道這段程式碼底是怎麼回事?或者從別人手上接手項目，並且不知道從哪裡開始?這樣的情況對開發者來說是比較常見的。 Python中有許多方法可以幫助我們理解程式碼的內部工作方式，因此當您從頭來看程式碼或寫入程式碼時，應該會更容易從停止的地方繼續下去。

在此我給大家舉個例子，我們可能會得到如下圖的程式碼。這還不是最糟糕的，但有一些事情需要我們去確認，例如:

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

在本文中，我將介紹如何透過文件、提示輸入和適當的變數名稱來提高應用程式/腳本的可讀性的5個基本技巧。

1.註解 

我們可以對程式碼做的第一件事是在某些行加上註釋，但要注意避免註解太多。註釋中需要闡述程式碼為什麼能起作用，或者為什麼某些事情要以某種方式完成，而不是它是如何實現的。 Python中的註解通常使用井號(#)來完成，可以跨一行也可以跨多行。

# Comment using the hashtag
# Another comment using the hashtag

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

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

在下面的範例中，程式碼中加入了一些註釋，以解釋某些程式碼行的工作流程和原因：

2.顯式型別 

Python語言是動態型別的，這表示變數型別只會在執行時被檢查。此外，變數可以在程式碼執行期間更改類型。另一方面，靜態類型涉及明確地聲明變數類型，並且在程式碼執行期間不能更改。

2014年，PEP 484引入了類型提示的概念，隨後這個概念引入了Python 3.5版本。這允許您明確地聲明變數類型。透過新增類型提示，可以顯著提高程式碼的可讀性。在下面的範例中，我們可以看出:

• 需要兩個參數
• 參數filename的類型是字串
• #參數start_depth的類型是float類型，同時該參數預設值為None
• 該函數將傳回一個pandas DataFrame物件

#根據型別提示，我們可以確切地知道函數需要什麼，以及它將返回什麼。

3.文件字串 

文件字串是緊接在函數或類別定義之後的字串。文件字串是一種很好的方式，可以詳細解釋函數的功能、需要什麼參數、將引發的異常、傳回值等等。此外，如果使用Sphinx之類的工具為程式碼建立線上文檔，則文件字串將自動提取並轉換為適當的文檔。下面的範例顯示了名為clay_volume的函數對應的文件字串。這裡我們可以指明每個參數的意思。這使它比基本的類型提示更詳細。您還可以包含更多關於函數背後的方法論的信息，例如學術參考資料或方程式。

當我們在程式碼的其他地方呼叫函數時，文件字串也是非常有幫助。例如，使用Visual  Studio編寫程式碼時，可以將滑鼠懸停在函數呼叫上，然後看到一個彈出窗口，顯示函數的功能及其需求。

如果您使用Visual Studio Code (VS Code)編輯您的Python程式碼，您可以使用autoDocstring這樣的擴充功能從而使創建文件字串的過程更容易。您可以輸入三個雙引號，並自動填入範本的其餘部分。你只需要填上細節。

提示：如果您已經在參數中宣告了類型，那麼它們將會自動選取。

4.具有可讀性的變數名稱 

有時候，當你在寫程式碼的時候，你不會太在意變數的名稱，特別是當時間比較緊張的時候。但是，如果您返回看程式碼時，會發現一系列名為x1或var123的變量，您可能無法一眼理解它們表示什麼。在下面的例子，有兩個變數f和d。我們可以透過查看程式碼的其他部分來猜測這類變數的含義，但這可能會花費時間，尤其是在程式碼很長的情況下。

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

5.避免魔法數字 

幻數是程式碼中的值，它們背後有一個無法解釋的意義，可以是常數。在程式碼中使用這些可能會導致歧義，尤其是不熟悉計算中使用數字的情況。此外，如果我們在多個地方有相同的神奇數字，當需要更新它，我們必須更新它的每個實例。然而，如果給這類數字分配一個合適的命名變量，那麼替換的過程就會容易得多。在下面的範例中，我們有一個函數，它計算一個名為result的值，並將其乘以0.6。這是什麼意思?它是一個轉換因子嗎?一個標量嗎?

#如果我們聲明一個變數並將該值賦給它，那麼我們就更有可能知道它是什麼。在這種情況下，將伽馬射線指數轉換為黏土體積所使用的是黏土與頁岩的比值。

6.最終程式碼 

在應用了上面的技巧之後，我們的最終程式碼現在看起來更清晰，更容易理解。

7.總結 

透過註解和文件字串向程式碼添加說明有助於幫助您和其他人理解程式碼正在做什麼。一開始可能會覺得這是一件苦差事，但隨著工具的使用和定期的練習，它會成為你的第二天性。

原文連結：https://towardsdatascience.com/5-essential-tips-to-improve-the-readability-of-your-python-code-a1d5e62a4bf0

#譯者介紹

趙青窕，51CTO社群編輯，從事多年驅動開發。研究興趣包含安全OS和網路安全領域，發表過網路相關專利。

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