pep 8 規范的一些記錄

一、pep8起源

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

二、官網鏈接

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

　　中文翻譯鏈接

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

三、重要總結

　　一致性問題：

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

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

　　代碼布局：

　　　　縮進四個空格代替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__暴露了子模塊。