Python 风格规范
作者: | 更新日期:
今天 hades 给我建议 python 的语句不要加分号，于是整理一下 python 的风格规范。
古老的风格
我以前是写 c 语言的，所以代码风格和 c 语言风格完全一样。
学习 python 后， 看到 python 的语句的分号是可选的，于是我遵循加分号的策略。
不过今天被告知 python 中不建议使用分号。
好吧，查一下 google 对 python 的规范比较好， google 毕竟是互联网行业的老大。
分号
简单的一句话：不要在行尾加分号, 也不要用分号将两条命令放在同一行.
缩进
缩进，python 很有特色的语法。
c 风格的程序员将会感到奇怪的，但是很容易适应。
使用 4 个空格代替一个 tab 是每个程序员需要遵守的。
所以关于缩进的规范还是：用四个空格代替一个tab.
行长度
每行不超过80个字符。
这个一般也不会超过 80 个字符，除非是定义一些常量时可能遇到。
比如 使用 urllib2 时需要指定 User-Agent， 但是这个 User-Agent 就很长。还有就是定义数据库的配置时和数据库语句都可能很长。
空行
顶级定义之间空两行, 比如函数或者类定义.
方法定义, 类定义与第一个方法之间, 都应该空一行.
函数或方法中, 某些地方要是你觉得合适, 就空一行.
这个一般也是编码习惯，其他语言也是这个样子的。
空格
空格的学问很大，每个语言一般进行语法分析的时候会忽略空格。
因此我们可以依靠空格来使程序看的更清晰一些。
注释
Python有一种独一无二的的注释方式: 使用文档字符串.
文档字符串是包, 模块, 类或函数里的第一个语句. 这些字符串可以通过对象的__doc__成员被自动提取, 并且被pydoc所用.
文档字符串的惯例是使用三个双引号 “””
函数和方法
一个函数必须要有文档字符串, 除非它满足以下条件:
- 外部不可见
- 非常短小
- 简单明了
文档字符串应该包含函数做什么, 以及输入和输出的详细描述. 通常, 不应该描述”怎么做”, 除非是一些复杂的算法. 文档字符串应该提供足够的信息, 当别人编写代码调用该函数时, 他不需要看一行代码, 只要看文档字符串就可以了. 对于复杂的代码, 在代码旁边加注释会比使用文档字符串更有意义.
关于函数的几个方面应该在特定的小节中进行描述记录， 这几个方面如下文所述. 每节应该以一个标题行开始. 标题行以冒号结尾. 除标题行外, 节的其他内容应被缩进2个空格.
- Args: 列出每个参数的名字, 并在名字后使用一个冒号和一个空格, 分隔对该参数的描述.如果描述太长超过了单行80字符,使用2或者4个空格的悬挂缩进(与文件其他部分保持一致). 描述应该包括所需的类型和含义. 如果一个函数接受*foo(可变长度参数列表)或者bar (任意关键字参数), 应该详细列出*foo和bar.
- Returns: (或者 Yields: 用于生成器) 描述返回值的类型和语义. 如果函数返回None, 这一部分可以省略.
- Raises: 列出与接口有关的所有异常.
类
类应该在其定义下有一个用于描述该类的文档字符串.
如果你的类有公共属性(Attributes), 那么文档中应该有一个属性(Attributes)段. 并且应该遵守和函数参数相同的格式.
如果一个类不继承自其它类, 就显式的从object继承. 嵌套类也一样.
字符串
即使参数都是字符串, 使用%操作符或者格式化方法格式化字符串.
避免在循环中用+和+=操作符来累加字符串. 由于字符串是不可变的, 这样做会创建不必要的临时对象, 并且导致二次方而不是线性的运行时间.
作为替代方案, 你可以将每个子串加入列表, 然后在循环结束后用 .join 连接列表.
在同一个文件中, 保持使用字符串引号的一致性.
命名约定
- 所谓”内部(Internal)”表示仅模块内可用, 或者, 在类内是保护或私有的.
- 用单下划线(_)开头表示模块变量或函数是protected的(使用import * from时不会包含).
- 用双下划线(__)开头的实例变量或方法表示类内私有.
- 将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.
- 对类名使用大写字母开头的单词(如CapWords, 即Pascal风格), 但是模块名应该用小写加下划线的方式(如lower_with_under.py).
Main
即使是一个打算被用作脚本的文件, 也应该是可导入的. 并且简单的导入不应该导致这个脚本的主功能(main functionality)被执行, 这是一种副作用. 主功能应该放在一个main()函数中.
def main():
"""
do something
"""
if __name__ == '__main__':
main()
