### 導航 - [索引](# "總目錄") - [下一頁](# "Python 3 支持") | - [上一頁](# "Flask 擴展開發") | - [Flask 0.10.1 文檔](#) ? # Pocoo 風格指引 Pocoo 風格指引是所有 Pocoo 項目的風格指引，包括 Flask 。這份風格指引在 Flask 補丁中是必須的，并且推薦在 Flask 擴展中使用。 一般而言， Pocoo 風格指引遵循 [**PEP 8**](http://www.python.org/dev/peps/pep-0008) [http://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' ~~~ ### 表達式和語句 常規空格規則: - 不對一元運算符使用空格（例如 - 、 ~ 等等），對圓括號同理 - 在二元運算符間使用空格 Good ~~~ exp = -1.05 value = (item_value / item_count) * offset / exp value = my_list[index] value = my_dict['key'] ~~~ Bad ~~~ 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 語句: 永遠不要用變量與常量做比較，而是把常量與變量做比較: God ~~~ if method == 'md5': pass ~~~ Bad ~~~ if 'md5' == method: pass ~~~ 比較: - 跟任意類型: == 和 != - 跟單例，使用 is 和 isnot （例如 fooisnotNone ） - 永遠不要與 True 或 False 做比較（比如永遠不要寫foo==False ，而使用 notfoo ） 否定包含檢查:使用 foonotinbar 而不是 notfooinbar實例檢查:用 isinstance(a,C) 而不是 type(A)isC ， 但通常試圖避免實例檢查，請對特性檢查。 ### 命名約定 - 類名: CamelCase ，縮寫詞大寫（ HTTPWriter 而非 HttpWriter ） - 變量名: lowercase_with_underscores - 方法和函數名: lowercase_with_underscores - 常量: UPPERCASE_WITH_UNDERSCORES - 預編譯正則表達式: name_re 被保護的成員以單個下劃線作為前綴，雙下劃線為 mixin 類保留。 有關鍵字的類上，在末尾添加下劃線。允許與內置組建沖突，并且**一定不要** 在用在變量名后添加下劃線的方式解決。如果函數需要訪問一個隱蔽的內置構件，重綁定內置構件到一個不同的名字作為替代。 函數和方法參數: - 類方法: cls 作為第一個參數 - 實例方法: self 作為第一個參數 - 屬性的 lambda 表達式應該把第一個參數替換為 x ，像 display_name=property(lambdax:x.real_nameorx.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) ~~~ ? 版權所有 2013, Armin Ronacher.