Flask 開發團隊內部 Python 編碼風格指南

一、Pocoo Team簡介

Pocoo團隊的成員來自Python社區，統一以Pocoo的名義參與多個Python庫和應用的開發工做。團隊由Georg Brandl和Armin Ronacher領導。

團隊項目

Pocoo團隊開發了許多廣受歡迎的項目，其中包括：

• Flask微網絡開發框架

• Jinja2模板引擎

• Pygments語法高亮包

• Sphinx文檔處理器

• Werzeug WSGI工具集

Pocoo團隊編碼風格指南適用於全部Pocoo團隊的項目。整體來講，Pocoo團隊編碼風格指南嚴格遵循了PEP8的要求，但略有一些不一樣之處，並進行了必定的擴展延伸。

二、代碼佈局（General Layout）

• 縮進（Indentation）

4個空格。不能使用Tab製表符，沒有例外。

• 每行最大長度

79個字符，若是必要能夠接受最多84個字符。儘可能避免代碼嵌套層級過多，能夠經過巧妙地使用break、continue和return語句實現。

• 長語句換行

編寫長語句時，可使用換行符（\）換行。在這種狀況下，下一行應該與上一行的最後一個「.」句點或「=」對齊，或者是縮進4個空格符：

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 Statements，指的是相似星戰中尤達大師那樣顛倒句子的正常順序）：

不要拿常量與變量進行對比，應該拿變量與常量進行對比。

好風格：

if method == 'md5':
    pass

壞風格：

if 'md5' == method:
    pass

比較：

• 任意類型之間的比較，使用「==」和「!=」。

• 與單例（singletons）進行比較時，使用is和is not。

• 永遠不要與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 classes）時才使用。

若是使用關鍵詞（keywords）做爲類名稱，應在名稱後添加後置下劃線（trailing underscore）。容許與內建變量重名，不要在變量名後添加下劃線進行區分。若是函數須要訪問重名的內建變量，請將內建變量從新綁定爲其餘名稱。

函數和方法的參數：

• 類方法：cls爲第一個參數。

• 實例方法：self爲第一個參數。

• property函數中使用匿名函數（lambdas）時，匿名函數的第一個參數能夠用x替代，例如：

  display_name = property(lambda x: x.real_name or x.username)。

五、文檔字符串

• 文檔字符串規範：

全部文檔字符串均以reStructuredText格式編寫，方便Sphinx處理。文檔字符串的行數不一樣，佈局也不同。若是隻有一行，表明字符串結束的三個引號與表明字符串開始的三個引號在同一行。若是爲多行，文檔字符串中的文本緊接着表明字符串開始的三個引號編寫，表明字符串結束的三個引號則本身獨立成一行。

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擴展（extension）經過官方團隊審覈，則必須提供相應的版權與協議文件。

六、註釋

註釋的規範與文檔字符串編寫規範相似。兩者均以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)

Refer：

[1] The Pocoo Style Guide

http://www.pocoo.org/internal/styleguide/