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團隊開發了許多廣受歡迎的項目，其中包括：
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)- 原文鏈接：http://www.pocoo.org/internal/styleguide/
- 譯者：EarlGrey@編程派
歡迎大家掃描下方二維碼關注我的公眾號“編程派”，謝謝支持！
本站文章除注明轉載外，均為本站原創或編譯。歡迎任何形式的轉載，但請務必注明來源編程派、作者及原文鏈接。
來自： http://codingpy.com/article/pocoo-internal-style-guide-cn/