俗話說：“沒有規(guī)矩不成方圓”。編程工作往往都是一個(gè)團(tuán)隊(duì)協(xié)同進(jìn)行，因而一致的編碼規(guī)范非常有必要，這樣寫成的代碼便于團(tuán)隊(duì)中的其他人員閱讀，也便于編寫者自己以后閱讀。
提示
關(guān)于本書的Python編碼規(guī)范借鑒了Python官方的PEP8編碼規(guī)范[1]和谷歌Python編碼規(guī)范[2]。
命名規(guī)范
程序代碼中到處都是標(biāo)識(shí)符，因此取一個(gè)一致并且符合規(guī)范的名字非常重要。Python中命名規(guī)范采用多種不同。不同的代碼元素命名不同，下面分類說明一下。
包名。全部小寫字母，中間可以由點(diǎn)分隔開，不推薦使用下劃線。作為命名空間，包名應(yīng)該具有唯一性，推薦采用公司或組織域名的倒置，如com.apple.quicktime.v2。
模塊名。全部小寫字母，如果是多個(gè)單詞構(gòu)成，可以用下劃線隔開，如dummy_threading。
類名。采用大駝峰法命名法[3]，如SplitViewController。
異常名。異常屬于類，命名同類命名，但應(yīng)該使用Error作為后綴。如FileNotFoundError。
變量名。全部小寫字母，如果是多個(gè)單詞構(gòu)成，可以用下劃線隔開。如果變量應(yīng)用于模塊或函數(shù)內(nèi)部，則變量名可以單下劃線開頭；如果變量類內(nèi)部私有使用變量名可以雙下劃線開頭。不要命名雙下劃線開頭和結(jié)尾的變量，這是Python保留的。另外，避免使用小寫L、大寫O和大寫I作為變量名。
函數(shù)名和方法名。命名同變量命名。如balance_account、_push_cm_exit。
常量名。全部大寫字母，如果是由多個(gè)單詞構(gòu)成，可以用下劃線隔開，如YEAR和WEEK_OF_MONTH。
命名規(guī)范示例如下：
_saltchars = _string.ascii_letters + _string.digits + './'
def mksalt(method=None):
if method is None:
method = methods[0]
s = '${}$'.format(method.ident) if method.ident else ''
s += ''.join(_sr.choice(_saltchars) for char in range(method.salt_chars))
return s
METHOD_SHA256 = _Method('SHA256', '5', 16, 63)
METHOD_SHA512 = _Method('SHA512', '6', 16, 106)
methods = []
for _method in (METHOD_SHA512, METHOD_SHA256, METHOD_MD5, METHOD_CRYPT):
_result = crypt('', _method)
if _result and len(_result) == _method.total_size:
methods.append(_method)
注釋規(guī)范
Python中注釋的語法有三種：單行注釋、多行注釋和文檔注釋。本節(jié)介紹如何規(guī)范使用這些注釋。
文件注釋
文件注釋就是在每一個(gè)文件開頭添加注釋，采用多行注釋。文件注釋通常包括如下信息：版權(quán)信息、文件名、所在模塊、作者信息、歷史版本信息、文件內(nèi)容和作用等。
下面看一個(gè)文件注釋的示例：
#
# 版權(quán)所有 2015 北京智捷東方科技有限公司
# 許可信息查看LICENSE.txt文件
# 描述:
# 實(shí)現(xiàn)日期基本功能
# 歷史版本:
# 2015-7-22: 創(chuàng)建 關(guān)東升
# 2015-8-20: 添加socket庫
# 2015-8-22: 添加math庫
#
上述注釋只是提供了版權(quán)信息、文件內(nèi)容和歷史版本信息等，文件注釋要根據(jù)本身的實(shí)際情況包括內(nèi)容。
文檔注釋
文檔注釋就是文檔字符串，注釋內(nèi)容能夠生成API幫助文檔，可以使用Python官方提供的pydoc工具從Python源代碼文件中提取信息這些信息，也可以生成HTML文件。所有公有的模塊、函數(shù)、類和方法都應(yīng)該進(jìn)行文檔注釋。
文檔注釋規(guī)范有些“苛刻”。文檔注釋推薦使用一對三重雙引號(hào)（"""）包裹起來，注意不推薦使用三重單引號(hào)（'''）。文檔注釋應(yīng)該位于被注釋的模塊、函數(shù)、類和方法內(nèi)部的第一條語句。如果文檔注釋一行能夠注釋完成，結(jié)束的三重雙引號(hào)也在同一行。如果文檔注釋很長，第一行注釋之后要留一個(gè)空行，然后剩下的注釋內(nèi)容，注釋內(nèi)容換行是要于開始三重雙引號(hào)對齊，最后結(jié)束的三重雙引號(hào)要獨(dú)占一行，并與開始三重雙引號(hào)對齊。
下面代碼是Python官方提供的base64.py文件一部分。
#! /usr/bin/env python3
"""Base16, Base32, Base64 (RFC 3548), Base85 and Ascii85 data encodings""" ①
# Modified 04-Oct-1995 by Jack Jansen to use binascii module
# Modified 30-Dec-2003 by Barry Warsaw to add full RFC 3548 support
# Modified 22-May-2007 by Guido van Rossum to use bytes everywhere
import re
import struct
import binascii
bytes_types = (bytes, bytearray) # Types acceptable as binary data
def _bytes_from_decode_data(s): ②
if isinstance(s, str):
try:
return s.encode('ascii')
except UnicodeEncodeError:
raise ValueError('string argument should contain only ASCII characters')
if isinstance(s, bytes_types):
return s
try:
return memoryview(s).tobytes()
except TypeError:
raise TypeError("argument should be a bytes-like object or ASCII "
"string, not %r" % s.__class__.__name__) from None
# Base64 encoding/decoding uses binascii
def b64encode(s, altchars=None):
"""Encode the bytes-like object s using Base64 and return a bytes object. ③
Optional altchars should be a byte string of length 2 which specifies an ④
alternative alphabet for the '+' and '/' characters. This allows an
application to e.g. generate url or filesystem safe Base64 strings.
""" ⑤
encoded = binascii.b2a_base64(s, newline=False)
if altchars is not None:
assert len(altchars) == 2, repr(altchars)
return encoded.translate(bytes.maketrans(b'+/', altchars))
return encoded
上述代碼第①行是只有一行的文檔注釋，代碼第③行~第⑤行是多行的文檔注釋，注意它的第一行后面是一個(gè)空行，代碼第④行接著進(jìn)行注釋，它要與開始三重雙引號(hào)對齊。代碼第⑤行是結(jié)束三重雙引號(hào)，它獨(dú)占一行的，而且與對齊開始三重雙引號(hào)對齊。另外，代碼第②行定義的函數(shù)沒有文檔注釋，這是因?yàn)樵摵瘮?shù)是模塊私有的，通過它的命名_bytes_from_decode_data可知它是私有的，下劃線開頭函數(shù)是模塊私有的。
代碼注釋
程序代碼中處理文檔注釋還需要在一些關(guān)鍵的地方添加代碼注釋，文檔注釋一般是給一些看不到源代碼的人看的幫助文檔，而代碼注釋是給閱讀源代碼的人參考的。代碼注釋一般是采用單行注釋和多行注釋。
示例代碼如下：
# Base32 encoding/decoding must be done in Python ①
_b32alphabet = b'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'
_b32tab2 = None
_b32rev = None
def b32encode(s):
"""Encode the bytes-like object s using Base32 and return a bytes object.
"""
global _b32tab2
# Delay the initialization of the table to not waste memory ②
# if the function is never called ③
if _b32tab2 is None:
b32tab = [bytes((i,)) for i in _b32alphabet]
_b32tab2 = [a + b for a in b32tab for b in b32tab]
b32tab = None
if not isinstance(s, bytes_types):
s = memoryview(s).tobytes()
leftover = len(s) % 5
# Pad the last quantum with zero bits if necessary ④
if leftover:
s = s + b'\0' * (5 - leftover) # Don't use += !
encoded = bytearray()
from_bytes = int.from_bytes
b32tab2 = _b32tab2
for i in range(0, len(s), 5):
c = from_bytes(s[i: i + 5], 'big')
encoded += (b32tab2[c >> 30] + # bits 1 – 10 ⑤
b32tab2[(c >> 20) & 0x3ff] + # bits 11 - 20
b32tab2[(c >> 10) & 0x3ff] + # bits 21 - 30
b32tab2[c & 0x3ff] # bits 31 - 40
)
# Adjust for any leftover partial quanta
if leftover == 1:
encoded[-6:] = b'======'
elif leftover == 2:
encoded[-4:] = b'===='
elif leftover == 3:
encoded[-3:] = b'==='
elif leftover == 4:
encoded[-1:] = b'='
return bytes(encoded)
上述代碼第②行~第④行都是單行注釋，要求與其后的代碼具有一樣的縮進(jìn)級(jí)別。代碼第①行~第③行是多行注釋，注釋時(shí)要求與其后的代碼具有一樣的縮進(jìn)級(jí)別。代碼第⑤行是尾端進(jìn)行注釋，這要求注釋內(nèi)容極短，應(yīng)該再有足夠的空白（至少兩個(gè)空格）來分開代碼和注釋。
使用TODO注釋
PyCharm等IDE工具都為源代碼提供了一些特殊的注釋，就是在代碼中加一些標(biāo)識(shí)，便于IDE工具快速定位代碼，TODO注釋就是其中的一種。TODO注釋雖然不是Python官方所提供的，但是主流的IDE工具也都支持TODO注釋。TODO注釋說明此處有待處理的任務(wù)，或代碼沒有編寫完成。
示例代碼如下：
import com.pkg2.hello as module1
from com.pkg2.hello import z
y = 20
# TODO 聲明函數(shù)
print(y) # 訪問當(dāng)前模塊變量y
print(module1.y) # 訪問com.pkg2.hello模塊變量y
print(z) # 訪問com.pkg2.hello模塊變量z
這些注釋在PyCharm工具的TODO視圖查看，如果沒有打開TODO視圖，可以將鼠標(biāo)放到PyCharm左下角
按鈕上，如圖5-1所示彈出的菜單，選擇TODO，打開如圖5-2所示的TODO視圖，單擊其中的TODO可跳轉(zhuǎn)到注釋處。
導(dǎo)入規(guī)范
導(dǎo)入語句總是放在文件頂部，位于模塊注釋和文檔注釋之后，模塊全局變量和常量之前。每一個(gè)導(dǎo)入語句只能導(dǎo)入一個(gè)模塊，示例代碼如下。
推薦：
import re
import struct
import binascii
不推薦：
import re, struct, binascii
但是如何from import后面可以多個(gè)代碼元素。
from codeop import CommandCompiler, compile_command
導(dǎo)入語句應(yīng)該按照從通用到特殊的順序分組，順序是：標(biāo)準(zhǔn)庫→第三方庫→自己模塊，每一組之間有一個(gè)空行，而且組中模塊是按照英文字典順序排序的。
import io ①
import os
import pkgutil
import platform
import re
import sys
import time ②
from html import unescape ③
from com.pkg1 import example ④
上述代碼中導(dǎo)入語句分為三組，代碼第①行~第②行是標(biāo)準(zhǔn)庫中的模塊，注意它的導(dǎo)入順序是有序的。代碼第③行是導(dǎo)入第三方庫中的模塊，代碼第④行是導(dǎo)入自己的模塊。
代碼排版
代碼排版包括空行、空格、斷行和縮進(jìn)等內(nèi)容。代碼排版內(nèi)容比較多，工作量很大，也非常重要。
空行
空行用以將邏輯相關(guān)的代碼段分隔開，以提高可讀性。下面是使用空行的規(guī)范。
- import語句塊前后保留兩個(gè)空行，示例代碼如下，其中①②處和③④處是兩個(gè)空行。
# Copyright 2007 Google, Inc. All Rights Reserved.
# Licensed to PSF under a Contributor Agreement.
"""Abstract Base Classes (ABCs) according to PEP 3119."""
①
②
from _weakrefset import WeakSet
③
④
- 函數(shù)聲明之前保留兩個(gè)空行，示例代碼如下，其中①②處處是兩個(gè)空行。
from _weakrefset import WeakSet
①
②
def abstractmethod(funcobj):
funcobj.__isabstractmethod__ = True
return funcobj
- 類聲明之前保留兩個(gè)空行，示例代碼如下，其中①②處是兩個(gè)空行。
①
②
class abstractclassmethod(classmethod):
__isabstractmethod__ = True
def __init__(self, callable):
callable.__isabstractmethod__ = True
super().__init__(callable)
- 方法聲明之前保留一個(gè)空行，示例代碼如下，其中①處是一個(gè)空行。
class abstractclassmethod(classmethod):
__isabstractmethod__ = True
①
def __init__(self, callable):
callable.__isabstractmethod__ = True
super().__init__(callable)
- 兩個(gè)邏輯代碼塊之間應(yīng)該保留一個(gè)空行，示例代碼如下，其中①處是一個(gè)空行。
def convert_timestamp(val):
datepart, timepart = val.split(b" ")
year, month, day = map(int, datepart.split(b"-"))
timepart_full = timepart.split(b".")
hours, minutes, seconds = map(int, timepart_full[0].split(b":"))
if len(timepart_full) == 2:
microseconds = int('{:0<6.6}'.format(timepart_full[1].decode()))
else:
microseconds = 0
①
val = datetime.datetime(year, month, day, hours, minutes, seconds, microseconds)
return val
空格
代碼中的有些位置是需要有空格的，這個(gè)工作量也很大。下面是使用空格的規(guī)范。
- 賦值符號(hào)“=”前后各有一個(gè)空格。
a = 10
c = 10
- 所有的二元運(yùn)算符都應(yīng)該使用空格與操作數(shù)分開。
a += c + d
- 一元運(yùn)算符：算法運(yùn)算符取反“-”和運(yùn)算符取反“~”。
b = 10
a = -b
y = \~b
- 括號(hào)內(nèi)不要有空格，Python中括號(hào)包括：小括號(hào)“()”、中括號(hào)“[]”和大括號(hào)“{}”。
推薦：
doque(cat[1], {dogs: 2}, [])
不推薦：
doque(cat[ 1 ], { dogs: 2 }, [ ])
不要在逗號(hào)、分號(hào)、冒號(hào)前面有空格，而是要在他們后面有一個(gè)空格，除非該符號(hào)已經(jīng)是行尾了。
推薦：
if x == 88:
print x, y
x, y = y, x
不推薦：
if x == 88 :
print x , y
x , y = y , x
- 參數(shù)列表、索引或切片的左括號(hào)前不應(yīng)有空格。
推薦：
doque(1)
dogs['key'] = list[index]
不推薦：
doque (1)
dict ['key'] = list [index]
縮進(jìn)
4個(gè)空格常被作為縮進(jìn)排版的一個(gè)級(jí)別。雖然在開發(fā)時(shí)程序員可以使用制表符進(jìn)行縮進(jìn)，而默認(rèn)情況下一個(gè)制表符等于8個(gè)空格，但是不同的IDE工具中一個(gè)制表符與空格對應(yīng)個(gè)數(shù)會(huì)有不同，所以不要使用制表符縮進(jìn)。
代碼塊的內(nèi)容相對于首行縮進(jìn)一個(gè)級(jí)別（4個(gè)空格），示例如下：
class abstractclassmethod(classmethod):
__isabstractmethod__ = True
def __init__(self, callable):
callable.__isabstractmethod__ = True
super().__init__(callable)
def __new__(mcls, name, bases, namespace, **kwargs):
cls = super().__new__(mcls, name, bases, namespace, **kwargs)
for base in bases:
for name in getattr(base, "__abstractmethods__", set()):
value = getattr(cls, name, None)
if getattr(value, "__isabstractmethod__", False):
abstracts.add(name)
cls.__abstractmethods__ = frozenset(abstracts)
return cls
斷行
一行代碼中最多79個(gè)字符。對于文檔注釋和多行注釋時(shí)一行最多72個(gè)字符，但是如何注釋中包含URL地址可以不受這個(gè)限制。否則，如果超過則需斷行，可以依據(jù)下面的一般規(guī)范斷開：
- 在逗號(hào)后面斷開。
bar = long_function_name(name1, name2,
name3, name4)
def long_function_name(var_one, var_two,
var_three, var_four):
- 在運(yùn)算符前面斷開。
name1 = name2 * (name3 + name4
- name5) + 4 * name6
盡量不要使用續(xù)行符（\），當(dāng)有括號(hào)（包括：大括號(hào)、中括號(hào)和小括號(hào)）則在括號(hào)中斷開，這樣可以不使用續(xù)行符。
def long_function_name(var_one, var_two,
var_three, var_four):
return var_one + var_two + var_three \ ①
+ var_four
name1 = name2 * (name3 + name4
- name5) + 4 * name6
bar = long_function_name(name1, name2,
name3, name4)
foo = {
long_dictionary_key: name1 + name2
- name3 + name4 - name5
}
c = list[name2 * name3
+ name4 - name5 + 4 * name6]
上述代碼第①行使用了續(xù)航符進(jìn)行斷行，其他的斷行都是在括號(hào)中實(shí)現(xiàn)的，所以省略了續(xù)行符。有時(shí)為了省略續(xù)行符，會(huì)將表達(dá)式用小括號(hào)包裹起來，如下代碼所示：
def long_function_name(var_one, var_two,
var_three, var_four):
return (var_one + var_two + var_three
+ var_four)
提示
在Python中反斜杠（\）可以作為續(xù)行符使用，告訴解釋器當(dāng)前行和下一行是連接在一起的。但如果在大括號(hào)、中括號(hào)和小括號(hào)中續(xù)行是隱式的。
本章小結(jié)
通過對本章內(nèi)容的學(xué)習(xí)，讀者可以了解到Python編碼規(guī)范，包括命名規(guī)范、注釋規(guī)范、導(dǎo)入規(guī)范和代碼排版等內(nèi)容。
配套視頻
http://www.zhijieketang.com/classroom/10/courses
配套源代碼
http://www.zhijieketang.com/group/8
紙質(zhì)版電商
京東：https://item.jd.com/12468732.html
當(dāng)當(dāng)：http://product.dangdang.com/25574315.html
作者微博：@tony_關(guān)東升
郵箱：eorient@sina.com
智捷課堂微信公共號(hào)：zhijieketang
Python讀者服務(wù)QQ群：565736812
-
大駝峰法命名是駝峰命名一種，駝峰命名是指混合使用大小寫字母來命名。駝峰命名分為小駝峰法和大駝峰法。小駝峰法就是第一個(gè)單詞是全部小寫，后面的單詞首字母大寫，如myRoomCount；大駝峰法是第一個(gè)單詞的首字母也大寫，如ClassRoom。 ?
