提高 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。通過代碼我們無法準確的知道該段代碼的具體含義
如果我們聲明一個變量并將該值分配給它，那么我們就有更好的機會知道它是什么。在這種情況下，它是用于將伽馬射線指數轉換為粘土體積的粘土與頁巖的比率。
總結
通過注釋和文檔字符串將文檔添加到我們的代碼中可以大大幫助自己和其他人了解代碼在做什么。確實，一開始可能感覺像是一件苦差事，但通過使用工具和定期練習，它可以成為你的第二天性。
