Python开发规范

• 背景
• Python语言规范
• Lint
• 导入
• 包
• 异常
• 全局变量
• 嵌套/局部/内部类或函数
• 列表推导（List Comprehensions）
• 默认迭代器和操做符
• 生成器
• Lambda 函数
• 条件表达式
• 默认参数值
• 属性（properties）
• True/False 的求值
• 过期的语言特性
• 词法做用域（Lexical Scoping）
• 函数与方法装饰器
• 线程
• 威力过大的特性
• Python风格规范
• 分号
• 行长度
• 括号
• 缩进
• 空行
• 空格
• Shebang
• 注释
• 类
• 字符串
• 文件和 sockets
• TODO注释
• 导入格式
• 语句
• 访问控制
• 命名
• Main
• 其余

 

背景

Python 是公司最主要的脚本语言，这个代码规范主要包含的是针对python的编程准则。

Python语言规范

Lint

对你的代码运行pylint

定义：

pylint是一个在Python源代码中查找bug的工具。对于C和C++这样的不那么动态的语言，这些bug一般由编译器来捕获。因为Python的动态特性，有些警告可能不对，不过伪告警应该不多。

优势：

能够捕获容易忽视的错误，例如输入错误，使用未赋值的变量等。

缺点： 

Pylint并不完美，要利用其优点，咱们有时侯须要：a) 围绕着它来写代码 b) 抑制其告警 c) 改进它，或者d) 忽略它。

结论：

确保对你的代码运行pylint,抑制不许确的警告，以便可以将其余警告暴露出来。你能够经过设置一个行注释来抑制告警。例如：

dict = 'something awful'  # Bad Idea... pylint: disable=redefined-builtin

pylint警告是以一个数字编号(如 C0112 )和一个符号名(如 empty-docstring )来标识的。在编写新代码或更新已有代码时对告警进行医治，推荐使用符号名来标识。若是警告的符号名不够见名知意，那么请对其增长一个详细解释。

采用这种抑制方式的好处是咱们能够轻松查找抑制并回顾它们。

你可使用命令 pylint --list-msgs 来获取pylint告警列表。可使用命令pylint --help-msg=C6409 ，以获取关于特定消息的更多信息。

相比较于以前使用的 pylint: disable-msg ，本文推荐使用 pylint: disable 。

要抑制”参数未使用”告警，你能够用”_”做为参数标识符，或者在参数名前加”unused_”。遇到不能改变参数名的状况，你能够经过在函数开头”提到”它们来消除告警。例如：

def foo(a, unused_b, unused_c, d=None, e=None):

    _ = d, e

    return a

导入

仅对包和模块使用导入

定义：

模块间共享代码的重用机制。

优势：

命名空间管理约定十分简单，每一个标识符的源都用一种一致的方式指示，x.Obj表示Obj对象定义在模块x中。

缺点：

模块名仍可能冲突，有些模块名太长，不太方便。

结论：

使用 import x 来导入包和模块。

使用 from x import y ，其中x是包前缀，y是不带前缀的模块名。

使用 from x import y as z，若是两个要导入的模块都叫作z或者y太长了。

例如，模块 sound.effects.echo 能够用以下方式导入：

from sound.effects import echo

...

echo.EchoFilter(input, output, delay=0.7, atten=4)

导入时不要使用相对名称，即便模块在同一个包中，也要使用完整包名，这能帮助你避免无心间导入一个包两次。

包

使用模块的全路径名来导入每一个模块

优势：

避免模块名冲突，查找包更容易。

缺点：

部署代码变难，由于你必须复制包层次。

结论：

全部的新代码都应该用完整包名来导入每一个模块。

应该像下面这样导入：

# Reference in code with complete name.

import sound.effects.echo

# Reference in code with just module name (preferred).

from sound.effects import echo

异常

容许使用异常，但必须当心

定义：

异常是一种跳出代码块的正常控制流来处理错误或者其它异常条件的方式。

优势：

正常操做代码的控制流不会和错误处理代码混在一块儿，当某种条件发生时，它也容许控制流跳过多个框架。例如，一步跳出N个嵌套的函数，而没必要继续执行错误的代码。

缺点：

可能会致使让人困惑的控制流，调用库时容易错过错误状况。

结论：

异常必须遵照特定条件：

1. 像这样触发异常：raise MyException("Error message") 或者 raise MyException ，不要使用两个参数的形式( raise MyException, "Error message" )或者过期的字符串异常( raise "Error message" )。

1. 模块或包应该定义本身的特定域的异常基类，这个基类应该从内建的Exception类继承，模块的异常基类应该叫作”Error”。
2. 当捕获异常时，使用 as 而不要用逗号。例如

3.  class Error(Exception):

    pass

4. 永远不要使用 except: 语句来捕获全部异常，也不要捕获 Exception 或者 StandardError ，除非你打算从新触发该异常，或者你已经在当前线程的最外层(记得仍是要打印一条错误消息)。在异常这方面，Python很是宽容，except: 真的会捕获包括Python语法错误在内的任何错误，使用except: 很容易隐藏真正的bug。
5. 尽可能减小try/except块中的代码量，try块的体积越大，指望以外的异常就越容易被触发。这种状况下，try/except块将隐藏真正的错误。
6. 使用finally子句来执行那些不管try块中有没有异常都应该被执行的代码，这对于清理资源经常颇有用，例如关闭文件。

8.  try:

9.      raise Error

10.except Error as error:

    pass

全局变量

避免全局变量

定义：

定义在模块级的变量。

优势：

偶尔有用。

缺点：

导入时可能改变模块行为，由于导入模块时会对模块级变量赋值。

结论：

避免使用全局变量，用类变量来代替，但也有一些例外：

1. 脚本的默认选项。
2. 模块级常量，例如：PI = 3.14159，常量应该全大写，用下划线链接。
3. 有时候用全局变量来缓存值或者做为函数返回值颇有用。
4. 若是须要，全局变量应该仅在模块内部可用，并经过模块级的公共函数来访问。

嵌套/局部/内部类或函数

鼓励使用嵌套/本地/内部类或函数

定义：

类能够定义在方法，函数或者类中；函数能够定义在方法或函数中；封闭区间中定义的变量对嵌套函数是只读的。

优势：

容许定义仅用于有效范围的工具类和函数。

缺点：

嵌套类或局部类的实例不能序列化(pickled)。

结论：

推荐使用。

列表推导（List Comprehensions）

能够在简单状况下使用

定义：

列表推导(list comprehensions)与生成器表达式(generator expression)提供了一种简洁高效的方式来建立列表和迭代器，而没必要借助map()，filter()，或者lambda。

优势：

简单的列表推导能够比其它的列表建立方法更加清晰简单。生成器表达式能够十分高效，由于它们避免了建立整个列表。

缺点：

复杂的列表推导或者生成器表达式可能难以阅读。

结论：

适用于简单状况，每一个部分应该单独置于一行：映射表达式，for语句，过滤器表达式。禁止多重for语句或过滤器表达式，复杂状况下仍是使用循环。

Yes:

  result = []

  for x in range(10):

      for y in range(5):

          if x * y > 10:

              result.append((x, y))

  for x in xrange(5):

      for y in xrange(5):

          if x != y:

              for z in xrange(5):

                  if y != z:

                      yield (x, y, z)

  return ((x, complicated_transform(x))

          for x in long_generator_function(parameter)

          if x is not None)

  squares = [x * x for x in range(10)]

  eat(jelly_bean for jelly_bean in jelly_beans

      if jelly_bean.color == 'black')

No:

  result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]

  return ((x, y, z)

          for x in xrange(5)

          for y in xrange(5)

          if x != y

          for z in xrange(5)

          if y != z)

默认迭代器和操做符

若是类型支持，就使用默认迭代器和操做符，好比列表，字典及文件等。

定义：

容器类型，像字典和列表，定义了默认的迭代器和关系测试操做符(in和not in)

优势：

默认操做符和迭代器简单高效，它们直接表达了操做，没有额外的方法调用。使用默认操做符的函数是通用的，它能够用于支持该操做的任何类型。

缺点：

你无法经过阅读方法名来区分对象的类型(例如，has_key()意味着字典)，不过这也是优势。

结论：

若是类型支持，就使用默认迭代器和操做符，例如列表、字典和文件。内建类型也定义了迭代器方法，优先考虑这些方法，而不是那些返回列表的方法。固然，这样遍历容器时，你将不能修改容器。

Yes:  for key in adict: ...

      if key not in adict: ...

      if obj in alist: ...

      for line in afile: ...

      for k, v in dict.iteritems(): ...

No:   for key in adict.keys(): ...

      if not adict.has_key(key): ...

      for line in afile.readlines(): ...

生成器

按需使用生成器。

定义：

所谓生成器函数，就是每当它执行一次生成(yield)语句，它就返回一个迭代器，这个迭代器生成一个值。生成值后，生成器函数的运行状态将被挂起，直到下一次生成。

优势：

简化代码，由于每次调用时，局部变量和控制流的状态都会被保存。比起一次建立一系列值的函数，生成器使用的内存更少

缺点：

没有。

结论：

鼓励使用，注意在生成器函数的文档字符串中使用”Yields:”而不是”Returns:”。

Lambda 函数

适用于单行函数

定义：

与语句相反，lambda在一个表达式中定义匿名函数，经常使用于为 map() 和 filter() 之类的高阶函数定义回调函数或者操做符。

优势：

方便。

缺点：

比本地函数更难阅读和调试，没有函数名意味着堆栈跟踪更难理解。因为lambda函数一般只包含一个表达式，所以其表达能力有限。

结论：

适用于单行函数，若是代码超过60-80个字符，最好仍是定义成常规(嵌套)函数。

对于常见的操做符，例如乘法操做符，使用 operator 模块中的函数以代替lambda函数。例如，推荐使用 operator.mul ，而不是 lambda x, y: x * y 。

条件表达式

适用于单行函数

定义：

条件表达式是对于if语句的一种更为简短的句法规则。例如：x = 1 if cond else 2 。

优势：

比if语句更加简短和方便。

缺点：

比if语句难于阅读，若是表达式很长，难于定位条件。

结论：

适用于单行函数，在其余状况下，推荐使用完整的if语句。

默认参数值

适用于大部分状况。

定义：

你能够在函数参数列表的最后指定变量的值，例如，def foo(a, b = 0): 。若是调用foo时只带一个参数，则b被设为0。若是带两个参数，则b的值等于第二个参数。

优势：

你常常会碰到一些使用大量默认值的函数，但偶尔(比较少见)你想要覆盖这些默认值。默认参数值提供了一种简单的方法来完成这件事，你不须要为这些罕见的例外定义大量函数。同时，Python也不支持重载方法和函数，默认参数是一种”仿造”重载行为的简单方式。

缺点：

默认参数只在模块加载时求值一次，若是参数是列表或字典之类的可变类型，这可能会致使问题。若是函数修改了对象(例如向列表追加项)，默认值就被修改了。

结论：

鼓励使用，不过注意不要在函数或方法定义中使用可变对象做为默认值。

Yes: def foo(a, b=None):

         if b is None:

             b = []

No:  def foo(a, b=[]):

         ...

No:  def foo(a, b=time.time()):  # The time the module was loaded???

         ...

No:  def foo(a, b=FLAGS.my_thing):  # sys.argv has not yet been parsed...

属性（properties）

访问和设置数据成员时，你一般会使用简单，轻量级的访问和设置函数，建议用属性（properties）来代替它们。

定义：

一种用于包装方法调用的方式，当运算量不大，它是获取和设置属性(attribute)的标准方式。

优势：

经过消除简单的属性(attribute)访问时显式的get和set方法调用，可读性提升了，用Pythonic的方式来维护类的接口，就性能而言，当直接访问变量是合理的，添加访问方法就显得琐碎而无心义。使用属性(properties)能够绕过这个问题，未来也能够在不破坏接口的状况下将访问方法加上。

缺点：

属性(properties)是在get和set方法声明后指定，这须要使用者在接下来的代码中注意：set和get是用于属性(properties)的(除了用 @property 装饰器建立的只读属性)必须继承自object类，这样可能隐藏好比操做符重载之类的反作用，继承时可能会让人困惑。

结论：

你一般习惯于使用访问或设置方法来访问或设置数据，它们简单而轻量，不过咱们建议你在新的代码中使用属性，只读属性应该用 @property 装饰器来建立。

若是子类没有覆盖属性，那么属性的继承可能看上去不明显，所以使用者必须确保访问方法间接被调用，以保证子类中的重载方法被属性调用(使用模板方法设计模式)。

Yes: import math

     class Square(object):

         """A square with two properties: a writable area and a read-only perimeter.

         To use:

         >>> sq = Square(3)

         >>> sq.area

         9

         >>> sq.perimeter

         12

         >>> sq.area = 16

         >>> sq.side

         4

         >>> sq.perimeter

         16

         """

         def __init__(self, side):

             self.side = side

         def __get_area(self):

             """Calculates the 'area' property."""

             return self.side ** 2

         def ___get_area(self):

             """Indirect accessor for 'area' property."""

             return self.__get_area()

         def __set_area(self, area):

             """Sets the 'area' property."""

             self.side = math.sqrt(area)

         def ___set_area(self, area):

             """Indirect setter for 'area' property."""

             self._SetArea(area)

         area = property(___get_area, ___set_area,

                         doc="""Gets or sets the area of the square.""")

         @property

         def perimeter(self):

             return self.side * 4

True/False 的求值

尽量使用隐式false

定义：

Python在布尔上下文中会将某些值求值为false，按简单的直觉来说，就是全部的”空”值都被认为是false，所以0， None，[]，{}，“” 都被认为是false。

优势：

使用Python布尔值的条件语句更易读也更不易犯错，大部分状况下也更快。

缺点：

对C/C++开发人员来讲，可能看起来有点怪。

结论：

尽量使用隐式的False，例如：使用 if foo: 而不是 if foo != []: ，不过仍是有一些注意事项须要你铭记在心：

1. 永远不要用==或者!=来比较单件，好比None，使用is或者is not。
2. 注意，当你写下 if x: 时，你其实表示的是 if x is not None ，例如：当你要测试一个默认值是None的变量或参数是否被设为其它值，这个值在布尔语义下多是false!
3. 永远不要用==将一个布尔量与false相比较，使用 if not x: 代替。若是你须要区分false和None，你应该用像 if not x and x is not None: 这样的语句。
4. 对于序列(字符串，列表，元组)，要注意空序列是false，所以 if not seq: 或者 if seq: 比if len(seq): 或 if not len(seq): 要更好。

1. 处理整数时，使用隐式false可能会得不偿失(即不当心将None当作0来处理)，你能够将一个已知是整型(且不是len()的返回结果)的值与0比较。

6.  Yes: if not users:

7.           print 'no users'

8.   

9.       if foo == 0:

10.         self.handle_zero()

11. 

12.     if i % 10 == 0:

13.         self.handle_multiple_of_ten()

14.No:  if len(users) == 0:

15.         print 'no users'

16. 

17.     if foo is not None and not foo:

18.         self.handle_zero()

19. 

20.     if not i % 10:

         self.handle_multiple_of_ten()

21. 注意‘0’(字符串)会被当作true。

过期的语言特性

尽量使用字符串方法取代字符串模块，使用函数调用语法取代apply()，使用列表推导，for循环取代filter()，map()以及reduce()。

定义：

当前版本的Python提供了你们一般更喜欢的替代品。

结论：

咱们不使用不支持这些特性的Python版本，因此没理由不用新的方式。

Yes: words = foo.split(':')

     [x[1] for x in my_list if x[2] == 5]

     map(math.sqrt, data)    # Ok. No inlined lambda expression.

     fn(*args, **kwargs)

No:  words = string.split(foo, ':')

     map(lambda x: x[1], filter(lambda x: x[2] == 5, my_list))

     apply(fn, args, kwargs)

词法做用域（Lexical Scoping）

推荐使用

定义：

嵌套的Python函数能够引用外层函数中定义的变量，可是不可以对它们赋值。变量绑定的解析是使用词法做用域，也就是基于静态的程序文本，对一个块中的某个名称的任何赋值都会致使Python将对该名称的所有引用当作局部变量，甚至是赋值前的处理。若是碰到global声明，该名称就会被视做全局变量。

一个使用这个特性的例子：

def get_adder(summand1):

    """Returns a function that adds numbers to a given number."""

    def adder(summand2):

        return summand1 + summand2

    return adder

优势：

一般能够带来更加清晰，优雅的代码，尤为会让有经验的Lisp和Scheme(还有Haskell，ML等)程序员感到欣慰。

缺点：

可能致使让人迷惑的bug，例以下面这个依据 PEP-0227 的例子：

i = 4

def foo(x):

    def bar():

        print i,

    # ...

    # A bunch of code here

    # ...

    for i in x:  # Ah, i *is* local to Foo, so this is what Bar sees

        print i,

    bar()

所以 foo([1, 2, 3]) 会打印 1 2 3 3 , 不是 1 2 3 4 。

(x是一个列表，for循环实际上是将x中的值依次赋给i。这样对i的赋值就隐式的发生了，整个foo函数体中的i都会被当作局部变量，包括bar()中的那个，这一点与C++之类的静态语言仍是有很大差异的)。

结论：

鼓励使用。

函数与方法装饰器

若是好处很显然，就明智而谨慎的使用装饰器

定义：

用于函数及方法的装饰器(也就是@标记)，最多见的装饰器是@classmethod 和@staticmethod，用于将常规函数转换成类方法或静态方法。不过，装饰器语法也容许用户自定义装饰器。特别地，对于某个函数 my_decorator ，下面的两段代码是等效的：

class C(object):

    @my_decorator

    def method(self):

        # method body ...

class C(object):

    def method(self):

        # method body ...

    method = my_decorator(method)

优势：

优雅的在函数上指定一些转换，该转换可能减小一些重复代码，保持已有函数不变(enforce invariants)等。

缺点：

装饰器能够在函数的参数或返回值上执行任何操做，这可能致使让人惊异的隐藏行为，并且，装饰器在导入时执行，从装饰器代码的失败中恢复更加不可能。

结论：

若是好处很明显，就明智而谨慎的使用装饰器。装饰器应该遵照和函数同样的导入和命名规则，装饰器的python文档应该清晰的说明该函数是一个装饰器。请为装饰器编写单元测试。

避免装饰器自身对外界的依赖(即不要依赖于文件、socket、数据库链接等)，由于装饰器运行时这些资源可能不可用(由 pydoc 或其它工具导入)，应该保证一个用有效参数调用的装饰器在全部状况下都是成功的。

装饰器是一种特殊形式的”顶级代码”，参考后面关于 Main 的章节。

线程

不要依赖内建类型的原子性。

虽然Python的内建类型例如字典看上去拥有原子操做，可是在某些情形下它们仍然不是原子的(即若是__hash__或__eq__被实现为Python方法)且它们的原子性是靠不住的，你也不能期望原子变量赋值(由于这个反过来依赖字典)。

优先使用Queue模块的 Queue 数据类型做为线程间的数据通讯方式，另外，使用threading模块及其锁原语(locking primitives)，了解条件变量的合适使用方式，这样你就可使用 threading.Condition 来取代低级别的锁了。

威力过大的特性

避免使用这些特性

定义：

Python是一种异常灵活的语言，它为你提供了不少花哨的特性，诸如元类(metaclasses)、字节码访问、任意编译(on-the-fly compilation)、动态继承、对象父类重定义(object reparenting)、导入黑客(import hacks)、反射、系统内修改(modification of system internals)等等。

优势：

强大的语言特性，能让你的代码更紧凑。

缺点：

使用这些很”酷”的特性十分诱人，但不是绝对必要，使用奇技淫巧的代码将更加难以阅读和调试。开始可能还好(对原做者而言)，但当你回顾代码，它们可能会比那些稍长一点可是很直接的代码更加难以理解。

结论：

在你的代码中避免这些特性。

Python风格规范

分号

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

行长度

每行不超过80个字符

例外：

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

不要使用反斜杠换行

Python会将圆括号，中括号和花括号中的行隐式的链接起来，你能够利用这个特色，若是须要，你能够在表达式外围增长一对额外的圆括号。

Yes: 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 = ('This will build a very long long '

     'long long long long long long string')

在注释中，若是必要，将长的URL放在一行上。

Yes: # See details at

     # http://www.example.com/documentation/csv_file_name_extension_full_specif.html

No:  # See details at

     # http://www.example.com/documentation/\

     # csv_file_name_extension_full_specif.html

注意上面例子中的元素缩进; 你能够在本文的缩进章节找到解释。

括号

宁缺毋滥的使用括号

除非是用于实现行链接，不然不要在返回语句或条件语句中使用括号，不过在元组两边使用括号是能够的。

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)

缩进

用4个空格来缩进代码

绝对不要用tab，也不要tab和空格混用，对于行链接的状况，你应该要么垂直对齐换行的元素(见“行长度”章节的示例)，或者使用4空格的悬挂式缩进(这时第一行不该该有参数):

Yes:   # Aligned with opening delimiter

       foo = long_function_name(var_one, var_two,

                                var_three, var_four)

       # Aligned with opening delimiter in a dictionary

       foo = {

           long_dictionary_key: value1 +

                                value2,

           ...

       }

       # 4-space hanging indent; nothing on first line

       foo = long_function_name(

           var_one, var_two, var_three,

           var_four)

       # 4-space hanging indent in a dictionary

       foo = {

           long_dictionary_key:

               long_dictionary_value,

           ...

       }

No:   # Stuff on first line forbidden

      foo = long_function_name(var_one, var_two,

          var_three, var_four)

      # 2-space hanging indent forbidden

      foo = long_function_name(

        var_one, var_two, var_three,

        var_four)

      # No hanging indent in a dictionary

      foo = {

          long_dictionary_key:

              long_dictionary_value,

              ...

      }

空行

顶级定义之间空两行，方法定义之间空一行

顶级定义之间空两行，好比函数或者类定义。方法定义，类定义与第一个方法之间，都应该空一行，函数或方法中，某些地方要是你以为合适，就空一行。

空格

按照标准的排版规范来使用标点两边的空格

括号内不要有空格。

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  # comment

     long_name = 2  # comment that should not be aligned

     dictionary = {

         "foo": 1,

         "long_name": 2,

         }

No:

     foo       = 1000  # comment

     long_name = 2     # comment that should not be aligned

     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解释器，可是在导入模块时，将会被忽略，所以只有被直接执行的文件中才有必要加入#!。

注释

确保对模块、函数、方法和行内注释使用正确的风格

文档字符串

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：

列出与接口有关的全部异常。

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

类

类应该在其定义下有一个用于描述该类的文档字符串，若是你的类有公共属性(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."""

块注释和行注释

最须要写注释的是代码中那些技巧性的部分，若是你在下次 代码审查 的时候必须解释一下，那么你应该如今就给它写注释。对于复杂的操做，应该在其操做开始前写上若干行注释。对于不是一目了然的代码，应在其行尾添加注释。

# 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 if i is a power of 2

为了提升可读性，注释应该至少离开代码2个空格。另外一方面，毫不要描述代码，假设阅读代码的人比你更懂Python，他只是不知道你的代码要作什么。

# BAD COMMENT: Now go through the b array and make sure whenever i occurs

# the next element is i+1

类

若是一个类不继承自其它类，就显式的从object继承，嵌套类也同样。

Yes: class SampleClass(object):

         pass

     class OuterClass(object):

         class InnerClass(object):

             pass

     class ChildClass(ParentClass):

         """Explicitly inherits from another class already."""

No: class SampleClass:

        pass

    class OuterClass:

        class InnerClass:

            pass

继承自 object 是为了使属性(properties)正常工做，而且这样能够保护你的代码，使其不受 PEP-3000的一个特殊的潜在不兼容性影响，这样作也定义了一些特殊的方法，这些方法实现了对象的默认语义，包括 __new__, __init__, __delattr__, __getattribute__, __setattr__, __hash__, __repr__, and __str__ 。

字符串

即便参数都是字符串，使用%操做符或者格式化方法格式化字符串，不过也不能一律而论，你须要在+和%之间好好断定。

Yes: x = a + b

     x = '%s, %s!' % (imperative, expletive)

     x = '{}, {}!'.format(imperative, expletive)

     x = 'name: %s; score: %d' % (name, n)

     x = 'name: {}; score: {}'.format(name, n)

No: x = '%s%s' % (a, b)  # use + in this case

    x = '{}{}'.format(a, b)  # use + in this case

    x = imperative + ', ' + expletive + '!'

    x = 'name: ' + name + '; score: ' + str(n)

避免在循环中用+和+=操做符来累加字符串，因为字符串是不可变的，这样作会建立没必要要的临时对象，而且致使二次方而不是线性的运行时间，做为替代方案，你能够将每一个子串加入列表，而后在循环结束后用 .join 链接列表(也能够将每一个子串写入一个 cStringIO.StringIO 缓存中)。

Yes: items = ['<table>']

     for last_name, first_name in employee_list:

         items.append('<tr><td>%s, %s</td></tr>' % (last_name, first_name))

     items.append('</table>')

     employee_table = ''.join(items)

No: employee_table = '<table>'

    for last_name, first_name in employee_list:

        employee_table += '<tr><td>%s, %s</td></tr>' % (last_name, first_name)

    employee_table += '</table>'

在同一个文件中，保持使用字符串引号的一致性，使用单引号’或者双引号”之一用以引用字符串，并在同一文件中沿用。在字符串内可使用另一种引号，以免在字符串中使用。pylint已经加入了这一检查。

Yes:

     Python('Why are you hiding your eyes?')

     Gollum("I'm scared of lint errors.")

     Narrator('"Good!" thought a happy Python reviewer.')

No:

     Python("Why are you hiding your eyes?")

     Gollum('The lint. It burns. It burns us.')

     Gollum("Always the great lint. Watching. Watching.")

为多行字符串使用三重双引号”“”而非三重单引号’‘’，当且仅当项目中使用单引号’来引用字符串时，才可能会使用三重’‘’为非文档字符串的多行字符串来标识引用。文档字符串必须使用三重双引号”“”，不过要注意，一般用隐式行链接更清晰，由于多行字符串与程序其余部分的缩进方式不一致。

Yes:

    print ("This is much nicer.\n"

           "Do it this way.\n")

No:

      print """This is pretty ugly.

  Don't do this.

  """

文件和 sockets

在文件和sockets结束时，显式的关闭它。

除文件外，sockets或其余相似文件的对象在没有必要的状况下打开，会有许多反作用，例如：

1. 它们可能会消耗有限的系统资源，如文件描述符，若是这些资源在使用后没有及时归还系统，那么用于处理这些对象的代码会将资源消耗殆尽。
2. 持有文件将会阻止对于文件的其余诸如移动、删除之类的操做。
3. 仅仅是从逻辑上关闭文件和sockets，那么它们仍然可能会被其共享的程序在无心中进行读或者写操做，只有当它们真正被关闭后，对于它们尝试进行读或者写操做将会跑出异常，并使得问题快速显现出来。

并且幻想当文件对象析构时，文件和sockets会自动关闭，试图将文件对象的生命周期和文件的状态绑定在一块儿的想法，都是不现实的，由于有以下缘由：

1. 没有任何方法能够确保运行环境会真正的执行文件的析构，不一样的Python实现采用不一样的内存管理技术，好比延时垃圾处理机制，延时垃圾处理机制可能会致使对象生命周期被任意无限制的延长。
2. 对于文件意外的引用，会致使对于文件的持有时间超出预期(好比对于异常的跟踪，包含有全局变量等)。

推荐使用 “with”语句 以管理文件：

with open("hello.txt") as hello_file:

    for line in hello_file:

        print line

对于不支持使用”with”语句的相似文件的对象，使用 contextlib.closing()：

import contextlib

with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:

    for line in front_page:

        print line

Legacy AppEngine 中Python 2.5的代码如使用”with”语句，须要添加 “from __future__ import with_statement”。

TODO注释

为临时代码使用TODO注释，它是一种短时间解决方案，不算完美，但够好了。

TODO注释应该在全部开头处包含”TODO”字符串，紧跟着是用括号括起来的你的名字，email地址或其它标识符，而后是一个可选的冒号，接着必须有一行注释，解释要作什么。主要目的是为了有一个统一的TODO格式，这样添加注释的人就能够搜索到(并能够按需提供更多细节)。写了TODO注释并不保证写的人会亲自解决问题，当你写了一个TODO，请注上你的名字。

# TODO(kl@gmail.com): Use a "*" here for string repetition.

# TODO(Zeke) Change this to use relations.

若是你的TODO是”未来作某事”的形式，那么请确保你包含了一个指定的日期(“2016年11月解决”)或者一个特定的事件(“等到全部的客户均可以处理XML请求就移除这些代码”)。

导入格式

每一个导入应该独占一行

Yes: import os

     import sys

No:  import os, sys

导入总应该放在文件顶部，位于模块注释和文档字符串以后，模块全局变量和常量以前，导入应该按照从最通用到最不通用的顺序分组：

1. 标准库导入
2. 第三方库导入
3. 应用程序指定导入

每种分组中，应该根据每一个模块的完整包路径按字典序排序，忽略大小写。

import foo

from foo import bar

from foo.bar import baz

from foo.bar import Quux

from Foob import ar

语句

一般每一个语句应该独占一行

不过，若是测试结果与测试语句在一行放得下，你也能够将它们放在同一行，若是是if语句，只有在没有else时才能这样作。毫不要对 try/except 这样作，由于try和except不能放在同一行。

Yes:

  if foo: bar(foo)

No:

  if foo: bar(foo)

  else:   baz(foo)

  try:               bar(foo)

  except ValueError: baz(foo)

  try:

      bar(foo)

  except ValueError: baz(foo)

访问控制

 

在Python中，对于琐碎又不过重要的访问函数，你应该直接使用公有变量来取代它们，这样能够避免额外的函数调用开销，当添加更多功能时，你能够用属性(property)来保持语法的一致性。

(重视封装的面向对象程序员看到这个可能会很反感，由于他们一直被教育：全部成员变量都必须是私有的! 其实，那真的是有点麻烦啊，试着去接受Pythonic哲学吧)

另外一方面，若是访问更复杂，或者变量的访问开销很显著，那么你应该使用像 get_foo() 和 set_foo()这样的函数调用。若是以前的代码行为容许经过属性(property)访问 ，那么就不要将新的访问函数与属性绑定，这样，任何试图经过老方法访问变量的代码就无法运行，使用者也就会意识到复杂性发生了变化。

命名

module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_VAR_NAME, instance_var_name, function_parameter_name, local_var_name.

应该避免的名称

1. 单字符名称，除了计数器和迭代器。
2. 包/模块名中的连字符(-)
3. 双下划线开头并结尾的名称(Python保留，例如__init__)

命名约定

1. 所谓”内部(Internal)”表示仅模块内可用，或者在类内是保护或私有的。
2. 用单下划线(_)开头表示模块变量或函数是protected的(使用import * from时不会包含)。
3. 用双下划线(__)开头的实例变量或方法表示类内私有。
4. 将相关的类和顶级函数放在同一个模块里，不像Java，不必限制一个类一个模块。
5. 对类名使用大写字母开头的单词(如CapWords，即Pascal风格)，可是模块名应该用小写加下划线的方式(如lower_with_under.py)，尽管已经有不少现存的模块使用相似于CapWords.py这样的命名，但如今已经不鼓励这样作，由于若是模块名碰巧和类名一致，这会让人困扰。

Python之父Guido推荐的规范

Type	Public	Internal
Modules	lower_with_under	_lower_with_under
Packages	lower_with_under
Classes	CapWords	_CapWords
Exceptions	CapWords
Functions	lower_with_under()	_lower_with_under()
Global/Class Constants	CAPS_WITH_UNDER	_CAPS_WITH_UNDER
Global/Class Variables	lower_with_under	_lower_with_under
Instance Variables	lower_with_under	_lower_with_under (protected) or __lower_with_under (private)
Method Names	lower_with_under()	_lower_with_under() (protected) or __lower_with_under() (private)
Function/Method Parameters	lower_with_under
Local Variables	lower_with_under

 

Main

即便是一个打算被用做脚本的文件，也应该是可导入的，而且简单的导入不该该致使这个脚本的主功能(main functionality)被执行，这是一种反作用，主功能应该放在一个main()函数中。

在Python中，pydoc以及单元测试要求模块必须是可导入的，你的代码应该在执行主程序前老是检查if __name__ == '__main__' ，这样当模块被导入时主程序就不会被执行。

def main():

      ...

if __name__ == '__main__':

    main()

全部的顶级代码在模块导入时都会被执行，要当心不要去调用函数，建立对象，或者执行那些不该该在使用pydoc时执行的操做。

其余

请务必保持代码的一致性

若是你正在编辑代码，花几分钟看一下周边代码，而后决定风格。若是它们在全部的算术操做符两边都使用空格，那么你也应该这样作。若是它们的注释都用标记包围起来，那么你的注释也要这样。

制定风格指南的目的在于让代码有规可循，这样人们就能够专一于”你在说什么”，而不是”你在怎么说”。咱们在这里给出的是全局的规范，可是本地的规范一样重要。若是你加到一个文件里的代码和原有代码截然不同，它会让读者不知所措，避免这种状况。

 

 

 

 

Ti 

Tip