作者sandwichC (没回应=挂站)
看板Translate-CS
标题[翻译] Google 建议的 Python 风格指南 27
时间Tue May 14 08:32:34 2013
原文网址：
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)