注釋
文檔字符串是包, 模塊, 類或函數里的第一個語句. 這些字符串可以通過對象的doc成員被自動提取, 并且被pydoc所用. (你可以在你的模塊上運行pydoc試一把, 看看它長什么樣). 我們對文檔字符串的慣例是使用三重雙引號""" ( PEP-257 ).
一個文檔字符串應該這樣組織: 首先是一行以句號, 問號或驚嘆號結尾的概述(或者該文檔字符串單純只有一行). 接著是一個空行.接著是文檔字符串剩下的部分, 它應該與文檔字符串的第一行的第一個引號對齊.
模塊注釋
每個文件應該包含一個許可樣板. 根據項目使用的許可(例如, Apache 2.0, BSD, LGPL, GPL), 選擇合適的樣板。如下圖中井號開頭的部分：
函數注釋
這里說的函數包括函數, 方法, 以及生成器。函數必須要有文檔字符串, 除非它滿足以下條件:
- 外部不可見
- 非常短小
- 簡單明了
目的：文檔字符串應該提供足夠的信息, 當別人編寫代碼調用該函數時, 他不需要看一行代碼, 只要看文檔字符串就可以了.
要寫: 函數做什么, 以及輸入和輸出的詳細描述.
不要寫: 描述”怎么做”, 除非是一些復雜的算法.
其他: 復雜的代碼, 在代碼旁邊加注釋會比使用文檔字符串更有意義.
函數的幾個方面應該在特定的小節中進行描述記錄, 每節應該以一個標題行開始. 標題行以冒號結尾. 除標題行外, 節的其他內容應被縮進2個空格.
Args:
列出每個參數的名字, 并在名字后使用一個冒號和一個空格, 分隔對該參數的描述. 如果描述太長超過了單行80字符,使用2或者4個空格的懸掛縮進(與文件其他部分保持一致). 描述應該包括所需的類型和含義. 如果一個函數接受*foo(可變長度參數列表)或者**bar (任意關鍵字參數), 應該詳細列出*foo和**bar.
Returns: (或者 Yields: 用于生成器)
描述返回值的類型和語義. 如果函數返回None, 這一部分可以省略.
Raises:
列出與接口有關的所有異常.
英文注釋：
函數注釋以動詞開頭，單數第三人稱，首字母大寫
好的函數，只用一個動詞
char1(str): The first Chinese character to be compared.
類注釋
描述該類, 如果你的類有公共屬性(Attributes), 那么文檔中應該有一個屬性(Attributes)段. 并且應該遵守和函數參數相同的格式.
塊注釋行注釋
最需要寫注釋的是代碼中那些技巧性的部分. 如果你在下次 代碼審查 的時候必須解釋一下, 那么你應該現在就給它寫注釋.
對于復雜的操作, 應該在其操作開始前寫上若干行注釋. 對于不是一目了然的代碼, 應在其行尾添加注釋.
導入
導入總應該放在文件頂部, 位于模塊注釋和文檔字符串之后, 模塊全局變量和常量之前.
每個導入應該獨占一行.
Yes: import os
import sys
No: import os, sys
導入應該按照從最通用到最不通用的順序分組:
- 標準庫導入
- 第三方庫導入
- 應用程序指定導入
每種分組中, 每部分之間空一行, 應該根據每個模塊的完整包路徑按字典序排序, 忽略大小寫.
import foo
from foo import bar
from foo.bar import baz
from foo.bar import Quux
from Foob import ar
