# Naming Conventions 命名規(guī)范

Python 庫(kù)的命名規(guī)范很亂，從來(lái)沒(méi)能做到完全一致。但是目前有一些推薦的命名標(biāo)準(zhǔn)。新的模塊和包(包括第三方框架)應(yīng)該用這套標(biāo)準(zhǔn)，但當(dāng)一個(gè)已有庫(kù)采用了不同的風(fēng)格，推薦保持內(nèi)部一致性。

## Overriding Principle 最重要的原則

那些暴露給用戶(hù)的 API 接口的命名，應(yīng)該遵循反映使用場(chǎng)景而不是實(shí)現(xiàn)的原則。

## Descriptive: Naming Styles 描述：命名風(fēng)格

有許多不同的命名風(fēng)格。這里能夠幫助大家識(shí)別正在使用什么樣的命名風(fēng)格，而不考慮他們?yōu)槭裁词褂谩?/p>

以下是常見(jiàn)的命名方式：

* b(單個(gè)小寫(xiě)字母)

* B(單個(gè)大寫(xiě)字母)

* lowercase 小寫(xiě)字母

* lower_case_with_underscores 使用下劃線(xiàn)分隔的小寫(xiě)字母

* UPPERCASE 大寫(xiě)字母

* UPPER_CASE_WITH_UNDERSCORES 使用下劃線(xiàn)分隔的大寫(xiě)字母

* CapitalizedWords(或者叫 CapWords，或者叫 CamelCase 駝峰命名法 —— 這么命名是因?yàn)樽帜缚瓷先ビ衅鸱耐庥^[5](https://blog.csdn.net/ratsniper/article/details/78954852#fn:4 "See footnote"))。有時(shí)候也被稱(chēng)為 StudlyCaps。

注意：當(dāng)在首字母大寫(xiě)的風(fēng)格中用到縮寫(xiě)時(shí)，所有縮寫(xiě)的字母用大寫(xiě)，因此，HTTPServerError 比 HttpServerError 好。

* mixedCase(不同于首字母大寫(xiě)，第一個(gè)單詞的首字母小寫(xiě))

* Capitalized_Words_With_Underscores(巨丑無(wú)比！)

也有用唯一的短前綴把相關(guān)命名組織在一起的方法。這在 Python 中不常用，但還是提一下。比如，os.stat()函數(shù)中包含類(lèi)似以 st_mode，st_size，st_mtime 這種傳統(tǒng)命名方式命名的變量。(這么做是為了與 POSIX 系統(tǒng)的調(diào)用一致，以幫助程序員熟悉它。)

X11 庫(kù)的所有公共函數(shù)都加了前綴 X。在 Python 里面沒(méi)必要這么做，因?yàn)閷傩院头椒ㄔ谡{(diào)用的時(shí)候都會(huì)用類(lèi)名做前綴，函數(shù)名用模塊名做前綴。

另外，下面這種用前綴或結(jié)尾下劃線(xiàn)的特殊格式是被認(rèn)可的(通常和一些約定相結(jié)合)：

* _single_leading_underscore：(單下劃線(xiàn)開(kāi)頭)弱“內(nèi)部使用”指示器。比如 from M import * 是不會(huì)導(dǎo)入以下劃線(xiàn)開(kāi)始的對(duì)象的。

* single_trailing_underscore_：(單下劃線(xiàn)結(jié)尾)這是避免和 Python 內(nèi)部關(guān)鍵詞沖突的一種約定，比如：Tkinter.Toplevel(master, class_=’ClassName’)

* `__double_leading_underscore`：(雙下劃線(xiàn)開(kāi)頭)當(dāng)這樣命名一個(gè)類(lèi)的屬性時(shí)，調(diào)用它的時(shí)候名字會(huì)做矯正(在類(lèi) FooBar 中，`__boo` 變成了`_FooBar__boo`；見(jiàn)下文)。

* `__double_leading_and_trailing_underscore__`：(雙下劃線(xiàn)開(kāi)頭，雙下劃線(xiàn)結(jié)尾)“magic”對(duì)象或者存在于用戶(hù)控制的命名空間內(nèi)的屬性，例如：`__init__`,`__import__` 或者`__file__`。除了作為文檔之外，永遠(yuǎn)不要命這樣的名。

## Prescriptive: Naming Conventions 約定俗成：命名約定

### Names to Avoid 應(yīng)避免的名字

永遠(yuǎn)不要使用字母‘l’(小寫(xiě)的 L)，‘O’(大寫(xiě)的 O)，或者‘I’(大寫(xiě)的 I)作為單字符變量名。

在有些字體里，這些字符無(wú)法和數(shù)字 0 和 1 區(qū)分，如果想用‘l’，用‘L’代替。

### Package and Module Names 包名和模塊名

模塊應(yīng)該用簡(jiǎn)短全小寫(xiě)的名字，如果為了提升可讀性，下劃線(xiàn)也是可以用的。Python 包名也應(yīng)該使用簡(jiǎn)短全小寫(xiě)的名字，但不建議用下劃線(xiàn)。

當(dāng)使用 C 或者 C++ 編寫(xiě)了一個(gè)依賴(lài)于提供高級(jí)(更面向?qū)ο?接口的 Python 模塊的擴(kuò)展模塊，這個(gè) C/C++ 模塊需要一個(gè)下劃線(xiàn)前綴(例如：_socket)

### Class Names 類(lèi)名

類(lèi)名一般使用首字母大寫(xiě)的約定。

在接口被文檔化并且主要被用于調(diào)用的情況下，可以使用函數(shù)的命名風(fēng)格代替。

注意，對(duì)于內(nèi)置的變量命名有一個(gè)單獨(dú)的約定：大部分內(nèi)置變量是單個(gè)單詞(或者兩個(gè)單詞連接在一起)，首字母大寫(xiě)的命名法只用于異常名或者內(nèi)部的常量。

### Exception Names 異常名

因?yàn)楫惓Ｒ话愣际穷?lèi)，所有類(lèi)的命名方法在這里也適用。然而，你需要在異常名后面加上“Error”后綴(如果異常確實(shí)是一個(gè)錯(cuò)誤)。

### Global Variable Names 全局變量名

(我們希望這一類(lèi)變量只在模塊內(nèi)部使用。)約定和函數(shù)命名規(guī)則一樣。

通過(guò) from M import * 導(dǎo)入的模塊應(yīng)該使用 **all** 機(jī)制去防止內(nèi)部的接口對(duì)外暴露，或者使用在全局變量前加下劃線(xiàn)的方式(表明這些全局變量是模塊內(nèi)非公有)。

### Function Names 函數(shù)名

函數(shù)名應(yīng)該小寫(xiě)，如果想提高可讀性可以用下劃線(xiàn)分隔。

大小寫(xiě)混合僅在為了兼容原來(lái)主要以大小寫(xiě)混合風(fēng)格的情況下使用(比如 threading.py)，保持向后兼容性。

### Function and method arguments 函數(shù)和方法參數(shù)

始終要將 self 作為實(shí)例方法的的第一個(gè)參數(shù)。

始終要將 cls 作為類(lèi)靜態(tài)方法的第一個(gè)參數(shù)。

如果函數(shù)的參數(shù)名和已有的關(guān)鍵詞沖突，在最后加單一下劃線(xiàn)比縮寫(xiě)或隨意拼寫(xiě)更好。因此 class_ 比 clss 更好。(也許最好用同義詞來(lái)避免這種沖突)

### Method Names and Instance Variables 方法名和實(shí)例變量

遵循這樣的函數(shù)命名規(guī)則：使用下劃線(xiàn)分隔小寫(xiě)單詞以提高可讀性。

在非共有方法和實(shí)例變量前使用單下劃線(xiàn)。

通過(guò)雙下劃線(xiàn)前綴觸發(fā) Python 的命名轉(zhuǎn)換規(guī)則來(lái)避免和子類(lèi)的命名沖突。

Python 通過(guò)類(lèi)名對(duì)這些命名進(jìn)行轉(zhuǎn)換：如果類(lèi) Foo 有一個(gè)叫 `__a` 的成員變量， 它無(wú)法通過(guò) `Foo.__a` 訪(fǎng)問(wèn)。(執(zhí)著的用戶(hù)可以通過(guò) `Foo._Foo__a` 訪(fǎng)問(wèn)。)一般來(lái)說(shuō)，前綴雙下劃線(xiàn)用來(lái)避免類(lèi)中的屬性命名與子類(lèi)沖突的情況。

注意：關(guān)于 `__names` 的用法存在爭(zhēng)論(見(jiàn)下文)。

### Constants 常量

常量通常定義在模塊級(jí)，通過(guò)下劃線(xiàn)分隔的全大寫(xiě)字母命名。例如： MAX_OVERFLOW 和 TOTAL。

### Designing for inheritance 繼承的設(shè)計(jì)

始終要考慮到一個(gè)類(lèi)的方法和實(shí)例變量(統(tǒng)稱(chēng)：屬性)應(yīng)該是共有還是非共有。如果存在疑問(wèn)，那就選非共有；因?yàn)閷⒁粋€(gè)非共有變量轉(zhuǎn)為共有比反過(guò)來(lái)更容易。

公共屬性是那些與類(lèi)無(wú)關(guān)的客戶(hù)使用的屬性，并承諾避免向后不兼容的更改。非共有屬性是那些不打算讓第三方使用的屬性；你不需要承諾非共有屬性不會(huì)被修改或被刪除。

我們不使用“私有(private)”這個(gè)說(shuō)法，是因?yàn)樵?Python 中目前還沒(méi)有真正的私有屬性(為了避免大量不必要的常規(guī)工作)。

另一種屬性作為子類(lèi) API 的一部分(在其他語(yǔ)言中通常被稱(chēng)為“protected”)。有些類(lèi)是專(zhuān)為繼承設(shè)計(jì)的，用來(lái)擴(kuò)展或者修改類(lèi)的一部分行為。當(dāng)設(shè)計(jì)這樣的類(lèi)時(shí)，要謹(jǐn)慎決定哪些屬性時(shí)公開(kāi)的，哪些是作為子類(lèi)的 API，哪些只能在基類(lèi)中使用。

貫徹這樣的思想，一下是一些讓代碼 Pythonic 的準(zhǔn)則：

* 公共屬性不應(yīng)該有前綴下劃線(xiàn)。

* 如果公共屬性名和關(guān)鍵字沖突，在屬性名之后增加一個(gè)下劃線(xiàn)。這比縮寫(xiě)和隨意拼寫(xiě)好很多。(然而，盡管有這樣的規(guī)則，在作為參數(shù)或者變量時(shí)，‘cls’是表示‘類(lèi)’最好的選擇，特別是作為類(lèi)方法的第一個(gè)參數(shù)。)

注意 1：參考之前的類(lèi)方法參數(shù)命名建議

* 對(duì)于單一的共有屬性數(shù)據(jù)，最好直接對(duì)外暴露它的變量名，而不是通過(guò)負(fù)責(zé)的 存取器(accessor)/突變(mutator) 方法。請(qǐng)記住，如果你發(fā)現(xiàn)一個(gè)簡(jiǎn)單的屬性需要成長(zhǎng)為一個(gè)功能行為，那么 Python 為這種將來(lái)會(huì)出現(xiàn)的擴(kuò)展提供了一個(gè)簡(jiǎn)單的途徑。在這種情況下，使用屬性去隱藏屬性數(shù)據(jù)訪(fǎng)問(wèn)背后的邏輯。

注意 1：屬性只在 new-style 類(lèi)中起作用。

注意 2：盡管功能方法對(duì)于類(lèi)似緩存的負(fù)面影響比較小，但還是要盡量避免。

注意 3：屬性標(biāo)記會(huì)讓調(diào)用者認(rèn)為開(kāi)銷(xiāo)(相當(dāng)?shù)?小，避免用屬性做開(kāi)銷(xiāo)大的計(jì)算。

* 如果你的類(lèi)打算用來(lái)繼承的話(huà)，并且這個(gè)類(lèi)里有不希望子類(lèi)使用的屬性，就要考慮使用雙下劃線(xiàn)前綴并且沒(méi)有后綴下劃線(xiàn)的命名方式。這會(huì)調(diào)用 Python 的命名轉(zhuǎn)換算法，將類(lèi)的名字加入到屬性名里。這樣做可以幫助避免在子類(lèi)中不小心包含了相同的屬性名而產(chǎn)生的沖突。

注意 1：只有類(lèi)名才會(huì)整合進(jìn)屬性名，如果子類(lèi)的屬性名和類(lèi)名和父類(lèi)都相同，那么你還是會(huì)有命名沖突的問(wèn)題。

注意 2：命名轉(zhuǎn)換會(huì)在某些場(chǎng)景使用起來(lái)不太方便，例如調(diào)試，`__getattr__()`。然而命名轉(zhuǎn)換的算法有很好的文檔說(shuō)明并且很好操作。

注意 3：不是所有人都喜歡命名轉(zhuǎn)換。盡量避免意外的名字沖突和潛在的高級(jí)調(diào)用。

## Public and internal interfaces 公共和內(nèi)部的接口

任何向后兼容保證只適用于公共接口，因此，用戶(hù)清晰地區(qū)分公共接口和內(nèi)部接口非常重要。

文檔化的接口被認(rèn)為是公開(kāi)的，除非文檔明確聲明它們是臨時(shí)或內(nèi)部接口，不受通常的向后兼容性保證。所有未記錄的接口都應(yīng)該是內(nèi)部的。

為了更好地支持內(nèi)省(introspection)，模塊應(yīng)該使用 `__all__` 屬性顯式地在它們的公共 API 中聲明名稱(chēng)。將 `__all__` 設(shè)置為空列表表示模塊沒(méi)有公共 API。

即使通過(guò) `__all__` 設(shè)置過(guò)，內(nèi)部接口(包，模塊，類(lèi)，方法，屬性或其他名字)依然需要單個(gè)下劃線(xiàn)前綴。

如果一個(gè)命名空間(包，模塊，類(lèi))被認(rèn)為是內(nèi)部的，那么包含它的接口也應(yīng)該被認(rèn)為是內(nèi)部的。

導(dǎo)入的名稱(chēng)應(yīng)該始終被視作是一個(gè)實(shí)現(xiàn)的細(xì)節(jié)。其他模塊必須不能間接訪(fǎng)問(wèn)這樣的名稱(chēng)，除非它是包含它的模塊中有明確的文檔說(shuō)明的 API，例如 os.path 或者是一個(gè)包里從子模塊公開(kāi)函數(shù)接口的 `__init__` 模塊。

總結(jié)

以上是生活随笔為你收集整理的python编码规范腾讯_Python PEP8 编码规范中文版的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。