Pocoo 风格指南

Pocoo 风格指南是所有 Pocoo 项目的风格指南，包括 Flask。此样式指南是 Patch to Flask 的要求和 Flask 扩展的建议。

一般来说，Pocoo 风格指南紧跟 PEP 8，但有一些小的差异和扩展。

总体布局

缩进：

4个真实空间。没有标签，没有例外。

最大线长：

79 个字符，如有必要，软限制为 84 个。通过巧妙地放置 break、continue 和 return 语句，尽量避免代码嵌套过多。

继续长声明：

要继续一个语句，您可以使用反斜杠，在这种情况下，您应该将下一行与最后一个点或等号对齐，或者缩进四个空格：

this_is_a_very_long(function_call, 'with many parameters') \
    .that_returns_an_object_with_an_attribute

MyModel.query.filter(MyModel.scalar > 120) \
             .order_by(MyModel.name.desc()) \
             .limit(10)

如果在带有括号或大括号的语句中中断，请与大括号对齐：

this_is_a_very_long(function_call, 'with many parameters',
                    23, 42, 'and even more')

对于包含许多项的列表或元组，在左大括号后立即中断：

items = [
    'this is the first', 'set of items', 'with more items',
    'to come in this line', 'like this'
]

空行：

顶级函数和类由两行分隔，其他所有内容由一行分隔。不要使用太多的空行来分隔代码中的逻辑段。例子：

def hello(name):
    print 'Hello %s!' % name


def goodbye(name):
    print 'See you %s.' % name


class MyClass(object):
    """This is a simple docstring"""

    def __init__(self, name):
        self.name = name

    def get_annoying_name(self):
        return self.name.upper() + '!!!!111'

表达式和语句

一般空格规则：

对于不是单词的一元运算符（例如：-、~ 等）以及括号的内侧，没有空格。
空格位于二元运算符之间。

好的：

exp = -1.05
value = (item_value / item_count) * offset / exp
value = my_list[index]
value = my_dict['key']

坏的：

exp = - 1.05
value = ( item_value / item_count ) * offset / exp
value = (item_value/item_count)*offset/exp
value=( item_value/item_count ) * offset/exp
value = my_list[ index ]
value = my_dict ['key']

尤达声明是不可行的：

永远不要将常量与变量进行比较，始终将变量与常量进行比较：

好的：

if method == 'md5':
    pass

坏的：

if 'md5' == method:
    pass

比较：

针对任意类型：== 和 !=
对抗带有 is 和 is not 的单例（例如：foo is not None）
永远不要与 True 或 False 进行比较（例如永远不要做 foo == False，而是做 not foo）

否定收容检查：

使用 foo not in bar 代替 not foo in bar

实例检查：

isinstance(a, C) 而不是 type(A) is C，但一般尽量避免实例检查。检查功能。

命名约定

类名：CamelCase，首字母缩写词保持大写（HTTPWriter 而不是 HttpWriter）
变量名称：lowercase_with_underscores
方法和函数名称：lowercase_with_underscores
常数：UPPERCASE_WITH_UNDERSCORES
预编译正则表达式：name_re

受保护的成员以单个下划线为前缀。双下划线是为 mixin 类保留的。

在带有关键字的类上，附加下划线。允许与内置函数发生冲突，并且 不得通过在变量名后添加下划线来解决 。如果函数需要访问隐藏的内置函数，请将内置函数重新绑定到不同的名称。

函数和方法参数：: ;* 类方法：cls 作为第一个参数

实例方法：self 作为第一个参数 属性的 lambda 可能会将第一个参数替换为 x，就像在 display_name = property(lambda x: x.real_name or x.username) 中一样

文档字符串

文档字符串约定：

所有文档字符串都使用 Sphinx 所理解的 reStructuredText 进行格式化。根据文档字符串中的行数，它们的布局不同。如果它只是一行，则结束三引号与开始在同一行，否则文本与开始引号和三引号在同一行上，该三引号在其自己的行上关闭字符串：

def foo():
    """This is a simple docstring"""


def bar():
    """This is a longer docstring with so much information in there
    that it spans three lines.  In this case the closing triple quote
    is on its own line.
    """

模块头：

模块头由 utf-8 编码声明（如果使用非 ASCII 字母，但一直建议使用）和标准文档字符串组成：

# -*- coding: utf-8 -*-
"""
    package.module
    ~~~~~~~~~~~~~~

    A brief description goes here.

    :copyright: (c) YEAR by AUTHOR.
    :license: LICENSE_NAME, see LICENSE_FILE for more details.
"""

请记住，正确的版权和许可文件是获得批准的 Flask 扩展的必要条件。

注释

注释规则类似于文档字符串。两者都使用 reStructuredText 进行格式化。如果注释用于记录属性，请在开头的井号 (#) 后放置一个冒号：

class User(object):
    #: the name of the user as unicode string
    name = Column(String)
    #: the sha1 hash of the password + inline salt
    pw_hash = Column(String)

Pocoo 风格指南 — Flask 文档

Pocoo 风格指南

总体布局

表达式和语句

命名约定

文档字符串

注释

目录