pep 8 規範的一些記錄

1、pep8起源

龜叔創立Python的初衷裏就有創立一個容易閱讀的編程語言，因此親自操刀寫了pep8 代碼規範，每一個項目開始前都要有一個共識，就是本身的代碼規範，pep8 就是一個很好的範本。

2、官網連接

　　https://www.python.org/dev/peps/pep-0008/

　　中文翻譯連接

　　https://my.oschina.net/u/1433482/blog/464444

3、重要總結

　　一致性問題：

　　　　風格指南強調一致性。項目、模塊或函數保持一致都很重要。

　　　　當遵循指南下降代碼一致性，可讀性的時候就沒必要強行修改。

　　代碼佈局：

　　　　縮進四個空格代替tab

　　　　行寬79個字符，文本長塊72個字符

　　字符編碼老是用UTF-8

　　導入模塊：

　　　　導入時單行導入，開頭導入，

　　　　順序爲標準庫，本地庫，第三方庫，

　　　　儘可能使用絕對路徑，不用通配符導入，

　　空格：

　　　　括號內沒有空格，

　　　　關鍵字參數和默認值參數的先後不要加空格

　　　　逗號，分號，冒號前無空格

　　　　運算符後有空格，

　　不推薦複合語句，一句一行

　　用英文寫註釋，及時更新註釋，少用行內註釋，文檔字符串：爲全部公共模塊、函數、類和方法書寫

　　命名：　　　　

　　　　最重要的原則

　　　　用戶可見的API命名應遵循使用約定而不是實現。（不太明白）

　　　　命名風格　　

• b(單個小寫字母)

• B(單個大寫字母)

• lowercase(小寫串)

• lower_case_with_underscores(帶下劃線的小寫)

• UPPERCASE(大寫串)

• UPPER_CASE_WITH_UNDERSCORES(帶下劃線的大寫串)

• CapitalizedWords(首字母大寫的單詞串或駝峯縮寫）注意: 使用大寫縮寫時，縮寫使用大寫字母更好。故 HTTPServerError 比 HttpServerError 更好。

• mixedCase(混合大小寫，第一個單詞是小寫)

• Capitalized_Words_With_Underscores（帶下劃線，首字母大寫，醜陋）

首尾有下劃線的狀況:

• _single_leading_underscore:(單前置下劃線): 弱內部使用標誌。 例如"from M import " 不會導入如下劃線開頭的對象。

• single_trailing_underscore_(單後置下劃線): 用於避免與 Python關鍵詞的衝突。 例如：Tkinter.Toplevel(master, class_='ClassName')

• __double_leading_underscore(雙前置下劃線): 當用於命名類屬性，會觸發名字重整。 (在類FooBar中，__boo變成 _FooBar__boo)。

• __double_leading_and_trailing_underscore__(雙先後下劃線)：用戶名字空間的魔法對象或屬性。例如:__init__ , __import__ or __file__，不要本身發明這樣的名字。

命名約定規範

• 避免採用的名字

決不要用字符'l'(小寫字母el)，'O'(大寫字母oh)，或 'I'(大寫字母eye) 做爲單個字符的變量名。一些字體中，這些字符不能與數字1和0區別。用'L' 代替'l'時。

• 包和模塊名

模塊名要簡短，所有用小寫字母，可以使用下劃線以提升可讀性。包名和模塊名相似，但不推薦使用下劃線。

模塊名對應到文件名，有些文件系統不區分大小寫且截短長名字，在 Unix上不是問題，但當把代碼遷移到 Mac、Windows 或 DOS 上時，就多是個問題。固然隨着系統的演進，這個問題已經不是常常出現。

另外有些模塊底層用C或C++ 書寫，並有對應的高層Python模塊，C/C++模塊名有一個前置下劃線 (如：_socket)。

• 類名

遵循CapWord。

接口須要文檔化而且能夠調用時，可能使用函數的命名規則。

注意大部份內置的名字是單個單詞（或兩個），CapWord只適用於異常名稱和內置的常量。

• 異常名

若是確實是錯誤，須要在類名添加後綴 "Error"。

• 全局變量名

變量儘可能只用於模塊內部，約定相似函數。

對設計爲經過 "from M import " 來使用的模塊，應採用 __all__ 機制來防止導入全局變量；或者爲全局變量加一個前置下劃線。

• 函數名

函數名應該爲小寫，必要時可用下劃線分隔單詞以增長可讀性。 mixedCase(混合大小寫)僅被容許用於兼容性考慮(如: threading.py)。

• 函數和方法的參數

實例方法第一個參數是 'self'。

類方法第一個參數是 'cls'。

若是函數的參數名與保留關鍵字衝突，一般在參數名後加一個下劃線。

• 方法名和實例變量

同函數命名規則。

非公開方法和實例變量增長一個前置下劃線。

爲避免與子類命名衝突，採用兩個前置下劃線來觸發重整。類Foo屬性名爲__a， 不能以 Foo.__a訪問。(執著的用戶仍是能夠經過Foo._Foo__a。) 一般雙前置下劃線僅被用來避免與基類的屬性發生命名衝突。

• 常量

常量一般在模塊級定義,由大寫字母用下劃線分隔組成。好比括MAX_OVERFLOW和TOTAL。

• 繼承設計

考慮類的方法和實例變量(統稱爲屬性)是否公開。若是有疑問，選擇不公開；把其改成公開比把公開屬性改成非公開要容易。

公開屬性可供全部人使用，並一般向後兼容。非公開屬性不給第三方使用、可變甚至被移除。

這裏不使用術語"private"， Python中沒有屬性是真正私有的。

另外一類屬性是子類API(在其餘語言中一般稱爲 "protected")。 一些類被設計爲基類，能夠擴展和修改。

謹記這些Python指南：

1. 公開屬性應該沒有前導下劃線。

2. 若是公開屬性名和保留關鍵字衝突，能夠添加後置下劃線

3. 簡單的公開數據屬性，最好只公開屬性名，沒有複雜的訪問/修改方法，python的Property提供了很好的封裝方法。 d.若是不但願子類使用的屬性，考慮用兩個前置下劃線(沒有後置下劃線)命名。

公共和內部接口

任何向後兼容的保證只適用於公共接口。

文檔化的接口一般是公共的，除非明說明是臨時的或爲內部接口、其餘全部接口默認是內部的。

爲了更好地支持內省，模塊要在__all__屬性列出公共API。

內部接口要有前置下劃線。

若是命名空間(包、模塊或類)是內部的，裏面的接口也是內部的。

導入名稱應視爲實現細節。其餘模塊不能間接訪名字，除非在模塊的API文檔中明確記載，如os.path中或包的__init__暴露了子模塊。