菜单

Python 编码规范(Google Python Style Guide)

2019年6月8日 - 计算机教程

Python 风格规范(Google)

源地址:http://www.runoob.com/w3cnote/google-python-styleguide.html

本项目并非 Google 官方项目, 而是由国内程序员凭热情创建和维护。

1、分号

不要在行尾加分号, 也不要用分号将两条命令放在同一行。

如果你关注的是 Google 官方英文版, 请移步 Google Style
Guide

2、行长度

每行不超过80个字符
以下情况除外:
长的导入模块语句
注释里的URL

以下代码中 Yes 表示推荐,No 表示不推荐。

3、不要使用反斜杠连接行。

Python会将 圆括号,
中括号和花括号中的行隐式的连接起来

, 你可以利用这个特点. 如果需要,
你可以在表达式外围增加一对额外的圆括号。
推荐: foo_bar(self, width, height, color=’black’, design=None, x=’foo’,
emphasis=None, highlight=0) if (width == 0 and height == 0 and color ==
‘red’ and emphasis == ‘strong’):
如果一个文本字符串在一行放不下, 可以使用圆括号来实现隐式行连接:
x = (‘这是一个非常长非常长非常长非常长 ‘
‘非常长非常长非常长非常长非常长非常长的字符串’)
在注释中,如果必要,将长的URL放在一行上。
Yes: # See details at #
http://www.example.com/us/developer/documentation/api/content/v2.0/csv\_file\_name\_extension\_full\_specification.html
No: # See details at #
http://www.example.com/us/developer/documentation/api/content/\
# v2.0/csv_file_402.com,name_extension_full_specification.html
注意上面例子中的元素缩进; 你可以在本文的
:ref:缩进 <indentation>部分找到解释.

分号

不要在行尾加分号, 也不要用分号将两条命令放在同一行。


4、括号

宁缺毋滥的使用括号
除非是用于实现行连接, 否则不要在返回语句或条件语句中使用括号.
不过在元组两边使用括号是可以的.
Yes: if foo: bar() while x: x = bar() if x and y: bar() if not x: bar()
return foo for (x, y) in dict.items(): …
No: if (x): bar() if not(x): bar() return (foo)
缩进

行长度

每行不超过80个字符

以下情况除外:

  1. 长的导入模块语句
  2. 注释里的URL

不要使用反斜杠连接行。

Python会将 圆括号,
中括号和花括号中的行隐式的连接起来
 ,
你可以利用这个特点. 如果需要, 你可以在表达式外围增加一对额外的圆括号。

推荐:

foo_bar(self, width, height, color='black', design=None, x='foo',
    emphasis=None, highlight=0)

  if (width == 0 and height == 0 and
   color == 'red' and emphasis == 'strong'):

如果一个文本字符串在一行放不下, 可以使用圆括号来实现隐式行连接:

x = ('这是一个非常长非常长非常长非常长 '
  '非常长非常长非常长非常长非常长非常长的字符串')

在注释中,如果必要,将长的URL放在一行上。

Yes:

 # See details at
  # http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html

No:

# See details at
# http://www.example.com/us/developer/documentation/api/content/\
# v2.0/csv_file_name_extension_full_specification.html

注意上面例子中的元素缩进; 你可以在本文的 :ref:`缩进
<indentation>`部分找到解释.

5、用4个空格来缩进代码

绝对不要用tab, 也不要tab和空格混用. 对于行连接的情况,
你应该要么垂直对齐换行的元素(见 :ref:行长度 <line_length> 部分的示例),
或者使用4空格的悬挂式缩进(这时第一行不应该有参数):
Yes: # 与起始变量对齐 foo = long_function_name(var_one, var_two,
var_three, var_four) # 字典中与起始值对齐 foo = {
long_dictionary_key: value1 + value2, … } # 4
个空格缩进,第一行不需要 foo = long_function_name( var_one, var_two,
var_three, var_four) # 字典中 4 个空格缩进 foo = {
long_dictionary_key: long_dictionary_value, … }
No: # 第一行有空格是禁止的 foo = long_function_name(var_one,
var_two, var_three, var_four) # 2 个空格是禁止的 foo =
long_function_name( var_one, var_two, var_three, var_four) #
字典中没有处理缩进 foo = { long_dictionary_key:
long_dictionary_value, … }

括号

宁缺毋滥的使用括号
除非是用于实现行连接, 否则不要在返回语句或条件语句中使用括号.
不过在元组两边使用括号是可以的.

Yes:

if foo:
 bar()
while x:
 x = bar()
if x and y:
 bar()
if not x:
 bar()
return foo
for (x, y) in dict.items(): ...

No: 

if (x):
 bar()
if not(x):
 bar()
return (foo)

6、空行

顶级定义之间空两行, 方法定义之间空一行
顶级定义之间空两行, 比如函数或者类定义. 方法定义,
类定义与第一个方法之间, 都应该空一行. 函数或方法中,
某些地方要是你觉得合适, 就空一行.

缩进

用4个空格来缩进代码
绝对不要用tab, 也不要tab和空格混用. 对于行连接的情况,
你应该要么垂直对齐换行的元素(见 :ref:`行长度 <line_length>`
部分的示例), 或者使用4空格的悬挂式缩进(这时第一行不应该有参数):

Yes: # 与起始变量对齐
  foo = long_function_name(var_one, var_two,
        var_three, var_four)

  # 字典中与起始值对齐
  foo = {
   long_dictionary_key: value1 +
        value2,
   ...
  }

  # 4 个空格缩进,第一行不需要
  foo = long_function_name(
   var_one, var_two, var_three,
   var_four)

  # 字典中 4 个空格缩进
  foo = {
   long_dictionary_key:
    long_dictionary_value,
   ...
  }


No: # 第一行有空格是禁止的
  foo = long_function_name(var_one, var_two,
   var_three, var_four)

  # 2 个空格是禁止的
  foo = long_function_name(
  var_one, var_two, var_three,
  var_four)

  # 字典中没有处理缩进
  foo = {
   long_dictionary_key:
    long_dictionary_value,
    ...
  }

7、空格

按照标准的排版规范来使用标点两边的空格
括号内不要有空格.
按照标准的排版规范来使用标点两边的空格
Yes: spam(ham[1], {eggs: 2}, [])
No: spam( ham[ 1 ], { eggs: 2 }, [ ] )
不要在逗号, 分号, 冒号前面加空格, 但应该在它们后面加(除了在行尾).
Yes: if x == 4: print x, y x, y = y, x
No: if x == 4 : print x , y x , y = y , x
参数列表, 索引或切片的左括号前不应加空格.
Yes: spam(1)
no: spam (1)
Yes: dict[‘key’] = list[index]
No: dict [‘key’] = list [index]
在二元操作符两边都加上一个空格, 比如赋值(=), 比较(==, <, >, !=,
<>, <=, >=, in, not in, is, is not), 布尔(and, or, not).
至于算术操作符两边的空格该如何使用, 需要你自己好好判断.
不过两侧务必要保持一致.
Yes: x == 1
No: x<1
当’=’用于指示关键字参数或默认参数值时, 不要在其两侧使用空格.
Yes: def complex(real, imag=0.0): return magic(r=real, i=imag)
No: def complex(real, imag = 0.0): return magic(r = real, i = imag)
不要用空格来垂直对齐多行间的标记, 因为这会成为维护的负担(适用于:, #,
=等):
Yes: foo = 1000 # 注释 long_name = 2 # 注释不需要对齐 dictionary = {
“foo”: 1, “long_name”: 2, }
No: foo = 1000 # 注释 long_name = 2 # 注释不需要对齐 dictionary = {
“foo” : 1, “long_name”: 2, }
Shebang
大部分.py文件不必以#!作为文件的开始. 根据
PEP-394
, 程序的main文件应该以 #!/usr/bin/python2或者
#!/usr/bin/python3开始.
(译者注: 在计算机科学中,
Shebang)
(也称为Hashbang)是一个由井号和叹号构成的字符串行(#!),
其出现在文本文件的第一行的前两个字符. 在文件中存在Shebang的情况下,
类Unix操作系统的程序载入器会分析Shebang后的内容,
将这些内容作为解释器指令, 并调用该指令,
并将载有Shebang的文件路径作为该解释器的参数. 例如,
以指令#!/bin/sh开头的文件在执行时会实际调用/bin/sh程序.)

空行

顶级定义之间空两行, 方法定义之间空一行
顶级定义之间空两行, 比如函数或者类定义. 方法定义,
类定义与第一个方法之间, 都应该空一行. 函数或方法中,
某些地方要是你觉得合适, 就空一行.

!先用于帮助内核找到Python解释器, 但是在导入模块时, 将会被忽略. 因此只有被直接执行的文件中才有必要加入#!.

空格

按照标准的排版规范来使用标点两边的空格
括号内不要有空格.
按照标准的排版规范来使用标点两边的空格

Yes: spam(ham[1], {eggs: 2}, [])
No: spam( ham[ 1 ], { eggs: 2 }, [ ] )

不要在逗号, 分号, 冒号前面加空格, 但应该在它们后面加(除了在行尾).

Yes: if x == 4:
   print x, y
  x, y = y, x


No: if x == 4 :
   print x , y
  x , y = y , x

参数列表, 索引或切片的左括号前不应加空格.

Yes: spam(1)
no: spam (1)
Yes: dict[‘key’] = list[index]
No: dict [‘key’] = list [index]

在二元操作符两边都加上一个空格, 比如赋值(=), 比较(==, <, >, !=,
<>, <=, >=, in, not in, is, is not), 布尔(and, or, not).
至于算术操作符两边的空格该如何使用, 需要你自己好好判断.
不过两侧务必要保持一致.

Yes: x == 1
No: x<1

当’=’用于指示关键字参数或默认参数值时, 不要在其两侧使用空格.

Yes: def complex(real, imag=0.0): return magic(r=real, i=imag)
No: def complex(real, imag = 0.0): return magic(r = real, i = imag)

不要用空格来垂直对齐多行间的标记, 因为这会成为维护的负担(适用于:, #,
=等):

Yes:
  foo = 1000 # 注释
  long_name = 2 # 注释不需要对齐

  dictionary = {
   "foo": 1,
   "long_name": 2,
   }


No:
  foo  = 1000 # 注释
  long_name = 2  # 注释不需要对齐

  dictionary = {
   "foo"  : 1,
   "long_name": 2,
   }

8、注释

确保对模块, 函数, 方法和行内注释使用正确的风格
文档字符串
Python有一种独一无二的的注释方式: 使用文档字符串. 文档字符串是包, 模块,
类或函数里的第一个语句. 这些字符串可以通过对象的doc成员被自动提取,
并且被pydoc所用. (你可以在你的模块上运行pydoc试一把, 看看它长什么样).
我们对文档字符串的惯例是使用三重双引号”””(
PEP-257
). 一个文档字符串应该这样组织: 首先是一行以句号,
问号或惊叹号结尾的概述(或者该文档字符串单纯只有一行). 接着是一个空行.
接着是文档字符串剩下的部分, 它应该与文档字符串的第一行的第一个引号对齐.
下面有更多文档字符串的格式化规范.

Shebang

大部分.py文件不必以#!作为文件的开始.
根据 PEP-394 ,
程序的main文件应该以 #!/usr/bin/python2或者 #!/usr/bin/python3开始.

(译者注:
在计算机科学中, Shebang) (也称为Hashbang)是一个由井号和叹号构成的字符串行(#!),
其出现在文本文件的第一行的前两个字符. 在文件中存在Shebang的情况下,
类Unix操作系统的程序载入器会分析Shebang后的内容,
将这些内容作为解释器指令, 并调用该指令,
并将载有Shebang的文件路径作为该解释器的参数. 例如,
以指令#!/bin/sh开头的文件在执行时会实际调用/bin/sh程序.)

#!先用于帮助内核找到Python解释器, 但是在导入模块时, 将会被忽略.
因此只有被直接执行的文件中才有必要加入#!.

9、模块

每个文件应该包含一个许可样板. 根据项目使用的许可(例如, Apache 2.0, BSD,
LGPL, GPL), 选择合适的样板.

注释

确保对模块, 函数, 方法和行内注释使用正确的风格
文档字符串

Python有一种独一无二的的注释方式: 使用文档字符串. 文档字符串是包,
模块, 类或函数里的第一个语句.
这些字符串可以通过对象的__doc__成员被自动提取, 并且被pydoc所用.
(你可以在你的模块上运行pydoc试一把, 看看它长什么样).
我们对文档字符串的惯例是使用三重双引号”””( PEP-257 ).
一个文档字符串应该这样组织: 首先是一行以句号,
问号或惊叹号结尾的概述(或者该文档字符串单纯只有一行). 接着是一个空行.
接着是文档字符串剩下的部分,
它应该与文档字符串的第一行的第一个引号对齐.
下面有更多文档字符串的格式化规范.

10、函数和方法

下文所指的函数,包括函数, 方法, 以及生成器.
一个函数必须要有文档字符串, 除非它满足以下条件:
外部不可见
非常短小
简单明了

文档字符串应该包含函数做什么, 以及输入和输出的详细描述. 通常,
不应该描述”怎么做”, 除非是一些复杂的算法. 文档字符串应该提供足够的信息,
当别人编写代码调用该函数时, 他不需要看一行代码,
只要看文档字符串就可以了. 对于复杂的代码,
在代码旁边加注释会比使用文档字符串更有意义.
关于函数的几个方面应该在特定的小节中进行描述记录, 这几个方面如下文所述.
每节应该以一个标题行开始. 标题行以冒号结尾. 除标题行外,
节的其他内容应被缩进2个空格.
Args:
列出每个参数的名字, 并在名字后使用一个冒号和一个空格,
分隔对该参数的描述.如果描述太长超过了单行80字符,使用2或者4个空格的悬挂缩进(与文件其他部分保持一致).
描述应该包括所需的类型和含义.
如果一个函数接受foo(可变长度参数列表)或者bar (任意关键字参数),
应该详细列出
foo和**bar.
Returns: (或者 Yields: 用于生成器)
描述返回值的类型和语义. 如果函数返回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

模块

每个文件应该包含一个许可样板. 根据项目使用的许可(例如, Apache 2.0, BSD,
LGPL, GPL), 选择合适的样板.

11、

类应该在其定义下有一个用于描述该类的文档字符串.
如果你的类有公共属性(Attributes),
那么文档中应该有一个属性(Attributes)段.
并且应该遵守和函数参数相同的格式.
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.”””

相关文章

发表评论

电子邮件地址不会被公开。 必填项已用*标注

网站地图xml地图