Pocoo 風格指引

Pocoo 風格指引是全部 Pocoo 項目的風格指引，包括 Flask 。這份風格指引 在 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']

不能使用 Yoda 語句:

永遠不要用常量與變量作比較，而是把變量與常量作比較:

好例子:

if method == 'md5':
    pass

糟糕的例子:

if 'md5' == method:
    pass

比較:

• 跟任意類型: == 和 !=
• 跟單例，使用 is 和 is not （例如 foo is not None ）
• 永遠不要與 True 或 False 作比較（好比永遠不要 寫 foo == False ，而是 notfoo ）

否認包含檢查:

使用 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

被保護的成員以單個下劃線做爲前綴，雙下劃線爲混合類保留。

在帶有關鍵字的類上，會添加結尾的下劃線。與內置構件衝突是容許的，而且 必定不要在用在變量名後添加下劃線的方式解決。若是函數須要訪問一個隱蔽 的內置構件，重綁定內置構件到一個不一樣的名字做爲替代。

函數和方法參數:

• 類方法: 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)