譯者 | 趙青窕
審校 | 孫淑娟
你是否經常回頭看看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和網絡安全領域，發表過網絡相關專利。
