原文網址：http://google-styleguide.googlecode.com/svn/trunk/pyguide.html

註解

確認模組、函式、方法、行內註解的正確用法。

文件註解 (doc string)

Python 有一個獨特的文件註解格式。文件註解是寫在 package, module, class,
或 function 開頭的一段字串，這個字串可用物件的 __doc__ member method
讀取，pydoc 也是使用這段文字 (試試對你寫的模組執行 pydoc 看會如何)。
使用文件註解的慣例是用三個雙引號來包住字串。一個文件註解的開頭要有
一行摘要，摘要的結束符號應該是句號、問號，或驚嘆號。摘要的下一行是空白行
。空白行的下一行的第一個字元應對齊摘要行的第一個雙引號。下面有更多文件
註解應遵守的格式。

模組 (module)

每一個檔案都應包含固定的 license 範本。選擇一個適合專案的範本 (例如：
Apache 2.0, BSD, LGPL, GPL)

函式 (function) 與方法 (method)

本段落中所指的函式，泛指方法 (method)，函式 (function)，及生成器
(generator)。

除非以下的幾個狀況 *全部* 符合，否則每個函式都必須有文件註解。

1. 不會在模組外被呼叫或使用
2. 非常短
3. 很直觀

一個文件註解應該要讓使用者只看文件而不需要看程式碼就知道該如何呼叫該函
式。故文件註解應包含函式的呼叫語法及函式的用途，而非函式實現的細節。對
於比較複雜不直觀的程式，註解與程式碼放在一起要比放在文件註解中合適。

函式中的某些部份要被放在特定的段落中，以下一一列出。每個段落的段頭是一
個標頭行，標頭行以冒號結束。除了標頭行，其他的部份應使用兩個空白字元縮
排。

Args:
列出每個參數名，參數名後加上冒號，空一格，然後是該參數的敘述。若敘述太
長，一行 (80 個字元) 容納不下，下一行應縮排二或四個空白，整個文件的縮
排方式應一致。敘述應包含參數的類型 (type) 及用途。

若一個函式的參數接受 *foo (可變長度參數序列 variable length argument
list) 或 **bar(任意關鍵字參數 arbitrary keyword argument)，文件註解中應
列為 *foo 及 **bar。

Returns: (若是生成函式則用 Yields:)
敘述回傳值的資料型態 (type) 及其意義與用途。若函式回傳 None，則不一定需
要有這個段落。

Raises:
列出所有此介面的例外。

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
"""Fetches rows from a Bigtable.

Retrieves rows pertaining to the given keys from the Table instance
represented by big_table. Silly things may happen if
other_silly_variable is not None.

Args:
big_table: An open Bigtable Table instance.
keys: A sequence of strings representing the key of each table row
to fetch.
other_silly_variable: Another optional variable, that has a much
longer name than the other args, and which does nothing.

Returns:
A dict mapping keys to the corresponding table row data
fetched. Each row is represented as a tuple of strings. For
example:

{'Serak': ('Rigel VII', 'Preparer'),
'Zim': ('Irk', 'Invader'),
'Lrrr': ('Omicron Persei 8', 'Emperor')}

If a key from the keys argument is missing from the dictionary,
then that row was not found in the table.

Raises:
IOError: An error occurred accessing the bigtable.Table object.
"""
pass

類別 (class)

在類別定義底下應包含此類別的文件註解。若類別包含公開屬性 (public
attribute)，則應寫在 attribute 段落中，並遵守函式中 Arg 段落中的格式。

class SampleClass(object):
"""Summary of class here.

Longer class information....
Longer class information....

Attributes:
likes_spam: A boolean indicating if we like SPAM or not.
eggs: An integer count of the eggs we have laid.
"""

def __init__(self, likes_spam=False):
"""Inits SampleClass with blah."""
self.likes_spam = likes_spam
self.eggs = 0

def public_method(self):
"""Performs operation blah."""

多行註釋及行註釋

最後一個該有註釋的地方是文件中較有技巧性的程式碼。若一段程式在下次的
code review 需要解釋，則應該要有註解。若需要多行註解來解釋較複雜的操作，
註釋應放在程式碼開始前。較不直觀的程式在行末應加上註解。

# We use a weighted dictionary search to find out where i is in
# the array. We extrapolate position based on the largest num
# in the array and the array size and then do binary search to
# get the exact number.

if i & (i-1) == 0: # true iff i is a power of 2

為了可讀性，註解應至少離程式碼兩個空白以上。

另一方面，絕不要敘述程式碼。假設閱讀該段程式碼的人比你更懂 Python (雖然
不一定懂你要做什麼)。

# BAD COMMENT: Now go through the b array and make sure whenever i occurs
# the next element is i+1

--
※ 發信站: 批踢踢實業坊(ptt.cc)
◆ From: 68.232.121.105
※ 編輯: sandwichC 來自: 68.232.121.105 (05/14 08:32)