本節內容如下：

• 什麽是註釋
• Python單行註釋
• Python多行註釋
• Python註釋規範

什麽是註釋

註釋不會被解釋器解釋執行，是用來說明程序功能，參數作用等。用來幫助自己或者團隊成員理解程序的。Python註釋分為單行註釋和多行註釋，多行註釋也稱塊註釋。查看原文

Python單行註釋

Python使用井號(#)表示單行註釋，例如：

Python多行註釋

Python 可以使用三引號表示多行註釋，也叫塊註釋。引號可以是單引號(‘)、也可以是雙引號(")，例如：

Python註釋規範

文檔字符串

Python有一種獨一無二的的註釋方式: 使用文檔字符串. 文檔字符串是包, 模塊, 類或函數裏的第一個語句. 這些字符串可以通過對象的doc成員被自動提取, 並且被pydoc所用. (你可以在你的模塊上運行pydoc試一把, 看看它長什麽樣). 我們對文檔字符串的慣例是使用三重雙引號"""( PEP-257 ). 一個文檔字符串應該這樣組織: 首先是一行以句號, 問號或驚嘆號結尾的概述(或者該文檔字符串單純只有一行). 接著是一個空行. 接著是文檔字符串剩下的部分, 它應該與文檔字符串的第一行的第一個引號對齊. 下面有更多文檔字符串的格式化規範.

模塊

每個文件應該包含一個許可樣板. 根據項目使用的許可(例如, Apache 2.0, BSD, LGPL, GPL), 選擇合適的樣板.

函數和方法

下文所指的函數,包括函數, 方法, 以及生成器. 一個函數必須要有文檔字符串, 除非它滿足以下條件:

1. 外部不可見
2. 非常短小
3. 簡單明了

文檔字符串應該包含函數做什麽, 以及輸入和輸出的詳細描述. 通常, 不應該描述"怎麽做", 除非是一些復雜的算法. 文檔字符串應該提供足夠的信息, 當別人編寫代碼調用該函數時, 他不需要看一行代碼, 只要看文檔字符串就可以了. 對於復雜的代碼, 在代碼旁邊加註釋會比使用文檔字符串更有意義. 關於函數的幾個方面應該在特定的小節中進行描述記錄， 這幾個方面如下文所述. 每節應該以一個標題行開始. 標題行以冒號結尾. 除標題行外, 節的其他內容應被縮進2個空格.

Args:

列出每個參數的名字, 並在名字後使用一個冒號和一個空格, 分隔對該參數的描述.如果描述太長超過了單行80字符,使用2或者4個空格的懸掛縮進(與文件其他部分保持一致). 描述應該包括所需的類型和含義. 如果一個函數接受*foo(可變長度參數列表)或者bar (任意關鍵字參數), 應該詳細列出*foo和bar.

Returns: (或者 Yields: 用於生成器)

描述返回值的類型和語義. 如果函數返回None, 這一部分可以省略.

Raises:

列出與接口有關的所有異常.

類

類應該在其定義下有一個用於描述該類的文檔字符串. 如果你的類有公共屬性(Attributes), 那麽文檔中應該有一個屬性(Attributes)段. 並且應該遵守和函數參數相同的格式.

塊註釋和行註釋

最需要寫註釋的是代碼中那些技巧性的部分. 如果你在下次 代碼審查 的時候必須解釋一下, 那麽你應該現在就給它寫註釋. 對於復雜的操作, 應該在其操作開始前寫上若幹行註釋. 對於不是一目了然的代碼, 應在其行尾添加註釋.

Python註釋