以正確的方式創建 Python 註釋

註釋是程序員添加到他們的代碼中以解釋該代碼應該做什麼的註釋。 將代碼轉化為動作的編譯器或解釋器會忽略註釋，但它們對於管理軟件項目可能是必不可少的。

註釋有助於向其他程序員解釋您的 Python 代碼，並且可以提醒您做出這些選擇的原因。 註釋通過幫助未來的程序員理解軟件背後的設計選擇，使調試和修改代碼變得更加容易。

儘管註釋主要是針對開發人員的，但編寫有效的註釋也有助於為您的代碼用戶生成出色的文檔。 借助 Sphinx for Python 項目等文檔生成器，代碼中的註釋可以為文檔提供內容。

讓我們深入了解 Python 中的註釋。

Python 中的註釋

根據 Python PEP 8 Style Guide，在編寫註釋時需要注意以下幾點：

• 評論應始終是完整而簡潔的句子。
• 與其發表難以理解或不准確的評論，不如完全沒有評論。
• 註釋應定期更新以反映代碼中的更改。
• 過多的註釋會分散注意力並降低代碼質量。 在代碼的目的很明顯的地方不需要註釋。

在 Python 中，以#符號開頭的行被聲明為註釋。 當 Python 解釋器在您的代碼中遇到#時，它會忽略該符號之後的任何內容並且不會產生任何錯誤。 聲明單行註釋有兩種方式：行內註釋和塊註釋。

行內評論

行內註釋提供變量和簡單操作的簡短描述，與代碼語句寫在同一行：

 border = x + 10 # Make offset of 10px

註釋在與代碼相同的語句中說明​​代碼的作用。

阻止評論

塊註釋用於描述代碼中的複雜邏輯。 Python 中的塊註釋的構造類似於內聯註釋——唯一的區別是塊註釋寫在單獨的一行上：

 import csv from itertools import groupby # Get a list of names in a sequence from the csv file with open('new-top-firstNames.csv') as f: file_csv = csv.reader(f) # Skip the header part: (sr, name, perc) header = next(file_csv) # Only name from (number, name, perc) persons = [ x[1] for x in file_csv] # Sort the list by first letter because # The groupby function looks for sequential data. persons.sort(key=lambda x:x[0]) data = groupby(persons, key=lambda x:x[0]) # Get every name as a list data_grouped = {} for k, v in data: # Get data in the form # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]} data_grouped[k] = list(v)

請注意，在使用塊註釋時，註釋寫在它們正在解釋的代碼之上。 Python PEP8 Style Guide 規定一行代碼不應超過七十九個字符，內聯註釋通常會超過這個長度。 這就是為什麼編寫塊註釋以在單獨的行中描述代碼的原因。

多行註釋

Python 本身不支持多行註釋，這意味著沒有專門的規定來定義它們。 儘管如此，經常使用跨越多行的註釋。

您可以通過在每行前面加上#來從幾個單行註釋中創建一個多行註釋：

 # interpreter # ignores # these lines

您還可以使用多行字符串語法。 在 Python 中，您可以通過將字符串括在"""三重雙引號或'''三重單引號中來定義多行字符串：

 print("Multi-Line Comment") """ This String is Multi line """

在上面的代碼中，多行字符串沒有分配給變量，這使得字符串像註釋一樣工作。 在運行時，Python 會忽略該字符串，並且它不會包含在字節碼中。 執行上面的代碼會產生以下輸出：

 Multi-Line Comment

特別評論

除了使您的代碼可讀之外，註釋在 Python 中也有一些特殊用途，例如規劃未來的代碼添加和生成文檔。

Python 文檔字符串註釋

在 Python 中，文檔字符串是解釋如何使用給定函數或類的多行註釋。 通過創建高質量的文檔字符串來改進代碼的文檔。 在使用函數或類並使用內置的help(obj)函數時，文檔字符串可能有助於提供對象的概述。

Python PEP 257 提供了在 Python 中聲明文檔字符串的標準方法，如下所示：

 from collections import namedtuple Person = namedtuple('Person', ['name', 'age']) def get_person(name, age, d=False): """ Returns a namedtuple("name", "age") object. Also returns dict('name', 'age') if arg `d` is True Arguments: name – first name, must be string age – age of person, must be int d – to return Person as `dict` (default=False) """ p = Person(name, age) if d: return p._asdict() return p

在上面的代碼中，文檔字符串提供了有關關聯函數如何工作的詳細信息。 使用 Sphinx 等文檔生成器，此文檔字符串可用於向您的項目用戶提供有關如何使用此方法的概述。

也可以使用內置的help()函數返回在函數或類簽名下方定義的文檔字符串。 help()函數將對像或函數名稱作為參數，並返回函數的文檔字符串作為輸出。 在上面的示例中，可以調用help(get_person)來顯示與get_person函數關聯的文檔字符串。 如果您使用-i標誌在交互式 shell 中運行上面的代碼，您可以看到 Python 將如何解析此文檔字符串。 通過鍵入python -i file.py運行上面的代碼。

help(get_person)函數調用為您的函數返回一個文檔字符串。 輸出包含get_person(name, age, d=False) ，這是 Python 自動添加的函數簽名。

get_person.__ doc__屬性也可用於以編程方式檢索和修改文檔字符串。 在上面的示例中添加“Some more new information”之後，它出現在對help(get_person)的第二次調用中。 不過，您不太可能需要像這樣在運行時動態更改文檔字符串。

TODO 評論

編寫代碼時，有時您會想要突出顯示某些行或整個塊以進行改進。 這些任務由 TODO 註釋標記。 當您計劃更新或更改代碼時，或者如果您希望通知項目的用戶或合作者文件代碼的特定部分仍有待編寫，TODO 註釋會派上用場。

TODO 註釋不應該寫成偽代碼——它們只需要簡要解釋尚未編寫的代碼的功能。

TODO 註釋和單行塊註釋非常相似，它們之間的唯一區別是 TODO 註釋必須以 TODO 前綴開頭：

 # TODO Get serialized data from the CSV file # TODO Perform calculations on the data # TODO Return to the user

重要的是要注意，儘管許多 IDE 可以為程序員突出顯示這些註釋，但 Python 解釋器對 TODO 註釋的看法與塊註釋沒有任何不同。

編寫 Python 註釋的最佳實踐

在撰寫評論以確保可靠性和質量時，應遵循許多最佳實踐。 以下是使用 Python 編寫高質量評論的一些技巧。

避免明顯的

陳述顯而易見的註釋不會為您的代碼增加任何價值，應該避免。 例如：

 x = x + 4 # increase x by 4

該註釋沒有用，因為它只是說明了代碼的作用，而沒有解釋為什麼需要這樣做。 註釋應該解釋它們所描述的代碼的“原因”而不是“什麼”。

重寫後更有用，上面的示例可能如下所示：

 x = x + 4 # increase the border width

保持 Python 註釋短小精悍

保持您的評論簡短易懂。 它們應該用標準的散文而不是偽代碼編寫，並且應該取代閱讀實際代碼以大致了解其功能的需要。 過多的細節或複雜的註釋不會使程序員的工作變得更輕鬆。 例如：

# return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r) def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

上面的評論提供了比讀者所需更多的信息。 註釋不應指定核心邏輯，而應提供代碼的一般摘要。 這條評論可以改寫為：

 # return area of cylinder def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

謹慎使用標識符

在註釋中應謹慎使用標識符。 更改標識符名稱或大小寫會使讀者感到困惑。 例子：

 # return class() after modifying argument def func(cls, arg): return cls(arg+5)

上面的評論提到了class和argument ，這兩個都沒有在代碼中找到。 這條評論可以改寫為：

 # return cls() after modifying arg def func(cls, arg): return cls(arg+5)

乾濕

當您編寫代碼時，您要堅持 DRY（不要重複自己）原則並避免 WET（所有內容都寫兩次）。

評論也是如此。 避免使用多個語句來描述您的代碼，並嘗試將解釋相同代碼的註釋合併為一個註釋。 但是，在合併評論時一定要小心：粗心地合併多個評論可能會導致違反風格指南的巨大評論，並且讀者難以理解。

請記住，註釋應該減少代碼的閱讀時間。

 # function to do x work def do_something(y): # x work cannot be done if y is greater than max_limit if y < 400: print('doing x work')

在上面的代碼中，評論被不必要地分散了，可以合併成一個評論：

 # function to do x if arg:y is less than max_limit def do_something(y): if y in range(400): print('doing x work')

一致的縮進

確保註釋的縮進水平與其所描述的代碼相同。 如果不是，則很難遵循。

例如，這條評論沒有縮進或定位不當：

 for i in range(2,20, 2): # only even numbers if verify(i): # i should be verified by verify() perform(x)

可以改寫如下：

 # only even numbers for i in range(2,20, 2): # i should be verified by verify() if verify(i): perform(x)

概括

註釋是編寫可理解代碼的重要組成部分。 您在撰寫評論方面所做的投資是您未來的自己——或其他需要在您的代碼庫上工作的開發人員——會感激的。 註釋還可以讓您更深入地了解您的代碼。

在本教程中，您了解了有關 Python 註釋的更多信息，包括各種類型的 Python 註釋、何時使用每種註釋以及創建它們時應遵循的最佳實踐。

寫出好的評論是一項需要學習和發展的技能。 要練習撰寫評論，請考慮返回並為您以前的一些項目添加評論。 如需靈感並查看最佳實踐，請查看 GitHub 上文檔齊全的 Python 項目。

當您準備好讓自己的 Python 項目上線時，Kinsta 的應用程序託管平台可以在幾秒鐘內將您的代碼從 GitHub 傳輸到雲端。