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

如何編寫規範的Python程式碼？Python開發文件又該怎樣寫？Python官方提供的編碼風格指南——PEP 8中，明確回答了上述兩個問題。PEP 8內容雖然廣泛， 但是大部分開發團隊並沒有止步於PEP 8中的要求。像Flask框架的開發團隊Pocoo，就是在此基礎上，編寫了自己內部的編碼規範，對PEP 8中的規定作了細微的調整，並進行了擴充套件延伸。我們一起來看看Pocoo團隊會給出怎樣的答案呢。（另外，也可以參考本站編譯的Python開發指南：最佳實踐精選一文，學習一些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個空格符：

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

如果你使用括號“()”或花括號“{}”為長語句換行，那麼下一行應與括號或花括號對齊：

:::python
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'

表示式和語句

一般空格規則

• 單目運算子與運算物件之間不空格（例如，-，~等），即使單目運算子位於括號內部也一樣。
• 雙目運算子與運算物件之間要空格。

好風格：

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

壞風格：

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

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

好風格：

:::python
if method == 'md5':
    pass

壞風格：

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

• 原文連結：http://www.pocoo.org/internal/styleguide/
• 譯者：EarlGrey@程式設計派

歡迎大家掃描下方二維碼關注我的公眾號“程式設計派”，謝謝支援！