所有 Pocoo 項目都遵循 Pocoo 風格指南， Flask 項目也不例外。 Flask 補丁必須 遵循這個指南，同時也推薦 Flask 擴展遵循這個指南。
一般而言， Pocoo 風格指南遵循[**PEP 8**](https://www.python.org/dev/peps/pep-0008)，有一些小差異和擴充。
## 書寫規范
* 縮進
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'
```
## 表達式和語句
* 常規空格規則
1. 不是單詞的一元運算符不使用空格（例如：`-`、`~`等等），在圓括號 也是這樣。
2. 用空格包圍二元運算符。
對
```
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
```
* 比較
1.針對任意類型使用`==`和`!=`
2.針對單一類型使用`is`和`isnot`（例如：`foo is not None`）
3.永遠不要與`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`
被保護的成員以單個下劃線作為前綴，混合類則使用雙下劃線。
如果使用關鍵字作為類的名稱，那么在名稱末尾添加下劃線。與內置構件沖突是允許 的，請**一定不要**用在變量名后添加下劃線的方式解決沖突。如果函數需要訪問 一個隱蔽的內置構件，請重新綁定內置構件到一個不同的名字。
函數和方法參數:
1. 類方法:`cls`作為第一個參數
2. 實例方法:`self`作為第一個參數
3.用于屬性的 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)
```
