Python 风格规范

古老的风格

我以前是写 c 语言的，所以代码风格和 c 语言风格完全一样。

学习 python 后， 看到 python 的语句的分号是可选的，于是我遵循加分号的策略。

不过今天被告知 python 中不建议使用分号。

好吧，查一下 google 对 python 的规范比较好， google 毕竟是互联网行业的老大。

分号

简单的一句话：不要在行尾加分号, 也不要用分号将两条命令放在同一行.

缩进

缩进，python 很有特色的语法。

c 风格的程序员将会感到奇怪的，但是很容易适应。

使用 4 个空格代替一个 tab 是每个程序员需要遵守的。

所以关于缩进的规范还是：用四个空格代替一个tab.

行长度

每行不超过80个字符。

这个一般也不会超过 80 个字符，除非是定义一些常量时可能遇到。

比如 使用 urllib2 时需要指定 User-Agent， 但是这个 User-Agent 就很长。还有就是定义数据库的配置时和数据库语句都可能很长。

空行

顶级定义之间空两行, 比如函数或者类定义.

方法定义, 类定义与第一个方法之间, 都应该空一行.

函数或方法中, 某些地方要是你觉得合适, 就空一行.

这个一般也是编码习惯，其他语言也是这个样子的。

空格

空格的学问很大，每个语言一般进行语法分析的时候会忽略空格。

因此我们可以依靠空格来使程序看的更清晰一些。

注释

Python有一种独一无二的的注释方式: 使用文档字符串.

文档字符串是包, 模块, 类或函数里的第一个语句. 这些字符串可以通过对象的__doc__成员被自动提取, 并且被pydoc所用.

文档字符串的惯例是使用三个双引号 “””

函数和方法

一个函数必须要有文档字符串, 除非它满足以下条件:

1. 外部不可见
2. 非常短小
3. 简单明了

文档字符串应该包含函数做什么, 以及输入和输出的详细描述. 通常, 不应该描述”怎么做”, 除非是一些复杂的算法. 文档字符串应该提供足够的信息, 当别人编写代码调用该函数时, 他不需要看一行代码, 只要看文档字符串就可以了. 对于复杂的代码, 在代码旁边加注释会比使用文档字符串更有意义.

关于函数的几个方面应该在特定的小节中进行描述记录， 这几个方面如下文所述. 每节应该以一个标题行开始. 标题行以冒号结尾. 除标题行外, 节的其他内容应被缩进2个空格.

• Args: 列出每个参数的名字, 并在名字后使用一个冒号和一个空格, 分隔对该参数的描述.如果描述太长超过了单行80字符,使用2或者4个空格的悬挂缩进(与文件其他部分保持一致). 描述应该包括所需的类型和含义. 如果一个函数接受*foo(可变长度参数列表)或者bar (任意关键字参数), 应该详细列出*foo和bar.
• Returns: (或者 Yields: 用于生成器) 描述返回值的类型和语义. 如果函数返回None, 这一部分可以省略.
• Raises: 列出与接口有关的所有异常.

类

类应该在其定义下有一个用于描述该类的文档字符串.

如果你的类有公共属性(Attributes), 那么文档中应该有一个属性(Attributes)段. 并且应该遵守和函数参数相同的格式.

如果一个类不继承自其它类, 就显式的从object继承. 嵌套类也一样.

字符串

即使参数都是字符串, 使用%操作符或者格式化方法格式化字符串.

避免在循环中用+和+=操作符来累加字符串. 由于字符串是不可变的, 这样做会创建不必要的临时对象, 并且导致二次方而不是线性的运行时间.

作为替代方案, 你可以将每个子串加入列表, 然后在循环结束后用 .join 连接列表.

在同一个文件中, 保持使用字符串引号的一致性.

命名约定

1. 所谓”内部(Internal)”表示仅模块内可用, 或者, 在类内是保护或私有的.
2. 用单下划线(_)开头表示模块变量或函数是protected的(使用import * from时不会包含).
3. 用双下划线(__)开头的实例变量或方法表示类内私有.
4. 将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.
5. 对类名使用大写字母开头的单词(如CapWords, 即Pascal风格), 但是模块名应该用小写加下划线的方式(如lower_with_under.py).

Main

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

def main():
    """
    do something
    """

if __name__ == '__main__':
    main()

参考资料

• zh-google-styleguide