python 文档字符串标准_Python编写规范

0x00 代码编排

1.缩进：使用4个空格缩进

2.行长度：每行不要超过80个字符

3.空行：顶级定义之间空两行，如函数或类的定义，方法定义、类定义与第一个方法之间都应该空一行。

4.分号：行尾不要有分号，也不要用分号将两条命令放在一行,除非是：

1.长的导入模块语句。

2.注释里的URL.

3.可以使用圆括号实现隐式行连接

0x01文档编排

1.导入：模块注释->文档字符串->导入->模块全局变量->常量

导入顺序：标准库导入->第三方库导入->应用程序指定库导入

2.import:不要在一行中import多个库，一行中只导入一个

0x02 空格

1.不要在逗号、分号、冒号前加空格，但应在他们后面加(除了在行尾)

2.二元操作符(赋值、比较、布尔)两边都加空格

3.当"="用于指示关键字参数或默认参数值是，不要再其两侧使用空格

4.","和"#"和"="不需要对齐，因为空格会成为维护的负担

0x03 注释

总体原则，错误的注释不如没有注释。

注释必须使用英文，最好是完整的句子，首字母大写，句后要有结束符，结束符后跟两个空格，开始下一句。如果是短语，可以省略结束符。

1.块注释：在一段代码前增加的注释。在"#"后加一空格。段落之间以只有"#"的行间隔。

2.行注释，在一句代码后加注释。进来少使用.

3.绝不要描述代码. 假设阅读代码的人比你更懂Python, 他只是不知道你的代码要做什么.

0x04 文档描述

1.为所有的共有模块、函数、类、方法写docstrings；非共有的没有必要，但是可以写注释(在def的下一行)。

2.如果docstring要换行，参考如下例子

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):

"""Inits SampleClass with blah."""

0x05 命名规范

#类

1.类名使用大写字母开头的单词(如CapWords, 即Pascal风格)

2.类的属性(方法和变量)命名使用全部小写的方式，可以使用下划线。

3.类的方法第一个参数必须是self，而静态方法第一个参数必须是cls。

4.用双下划线(__)开头的实例变量或方法表示类内私有.

#函数

1.函数命名使用全部小写的方式，可以使用下划线。

2.变量也用小写加下划线的方式，即this_is_a_variable=1

3.常量命名使用全部大写的方式，可以使用下划线。

#包和模块

1.包命名尽量短小，使用全部小写的方式，不可以使用下划线。

2.模块名尽量短小，应该用小写加下划线的方式(如lower_with_under.py).

3.用单下划线(_)开头表示模块变量或函数是protected的(使用import * from时不会包含).

1.尽量单独使用小写字母'l'，大写字母'O'等容易混淆的字母。

0x06 Main

即使是一个打算被用作脚本的文件, 也应该是可导入的.

并且简单的导入不应该导致这个脚本的主功能(main functionality)被执行

代码应该在执行主程序前总是检查 if __name__ == '__main__'

def main():

...

if __name__ == '__main__':

main()

0x07 字符串

避免在循环中用+和+=来累加字符串，可以将每个子串加入列表，然后再循环结束后使用.join连接列表

items = ['

for last_name, first_name in employee_list:

items.append('

%s, %s' % (last_name, first_name))

items.append('

')

employee_table = ''.join(items)

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

多行字符串使用三重"双"引号，不过通常使用括号隐式连接

0x08 其他

括号：宁缺毋滥的使用括号

类：若一个类不继承自其它类，就显式的从object继承,即使是嵌套类

语句：通常每个语句独占一行，try/except一定不放在一行

文件和sockets：在文件和sockets结束时，显式的关闭它，推荐with语句管理文件

若未作声明则文章版权归本人(@reber)所有，转载请注明原文链接：