提高Python代碼可讀性的5個技巧分享

Posted on by

不知道小夥伴們是否有這樣的困惑，當我們回顧自己 6 個月前編寫的一些代碼時，往往會看的一頭霧水，或者是否當我們接手其他人的代碼時，

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代碼可讀性的5個技巧分享的文章就介紹到這瞭,更多相關Python代碼可讀性內容請搜索WalkonNet以前的文章或繼續瀏覽下面的相關文章希望大傢以後多多支持WalkonNet！

推薦閱讀：