Python代碼格式規範——PEP8

目錄

• Python：關于代碼的格式規範
• • 1.源檔案編碼、導入
  • 2.命名
  • • 2.1 約定成俗的下劃線命名
    • 2.2 函數、方法、常量名
    • 2.3 變量命名
    • • 2.3.1 單字元變量命名
      • 2.3.2 全局變量命名
      • 2.3.3 類型變量名
      • 2.3.4 執行個體變量名
    • 2.3 子產品、包、類名
  • 3.注釋
  • 4.換行
  • 5.空行與空格
  • • 5.1 空行
    • 5.2 空格
  • 6.縮進
  • 7.字元串與尾部逗号
  • • 7.1 字元串
    • 7.2 尾部逗号

Python：關于代碼的格式規範

為了提高代碼的可讀性：編寫的代碼很多時候并不是給自己一個人看的，實際上給别人閱讀的次數要頻繁得多。

當然，根據實際情況來看，如果這麼做反而降低了可讀性，那也不是非要遵守不可，總之，保證可讀性！

Python中的格式規範：編碼風格指南——PEP8，原文請移步官網：PEP8

這裡隻做一個簡要概括。(其實在像Pycham這樣的IDE中都有自動的機制，Pycham中在輸入字元時就會提示有沒有符合PEP8規範，而且快捷鍵Ctrl + Alt +L 也可以使代碼格式化，讓排版符合PEP8格式）

1.源檔案編碼、導入

Python核心釋出中的代碼應該始終使用UTF-8，且不應有編碼聲明，字元串和注釋、Python标準庫中的所有辨別符必須使用ASCII辨別符，在可行的地方使用英文單詞。

為所有公共子產品，函數，類和方法書寫文檔字元串。對非公開的方法書寫文檔字元串是沒有必要的，但應該寫注釋描述這個方法是做什麼的，這些注釋應該寫在def行後面。

多行文檔字元串以一行 “”" 結束。

子產品級别的内置屬性（名字有前後雙下劃線的），例如__all__, 應該放置在子產品的文檔字元串後，任意import語句之前，from __future__導入除外。Python強制要求from __future__導入必須在任何代碼之前，隻能在子產品級文檔字元串之後。

導入通常是單獨一行，位于檔案頂部，在子產品注釋和字元串文檔之後，在子產品的全局變量和常量之前。

一般推薦絕對導入，但在處理複雜包布局時，絕對導入過于冗長，明确的相對導入可以用來替代絕對導入。

"""This is the example module.

This module does stuff.
"""

from __future__ import barry_as_FLUFL

__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'

import os
import sys
from subprocess import Popen, PIPE

# 明确的相對導入
from . import sibling
from .sibling import example
           

2.命名

命名遵循反應用法的原則，可讀性很重要。

2.1 約定成俗的下劃線命名

2.1.1 單前導下劃線：“内部使用”标志。例如

from M import *

不會導入以下劃線開頭的對象。

2.2.2 單後置下劃線：按慣例使用避免與Python關鍵字沖突，例如

Tkinter.Toplevel(master, class_='ClassName')

2.2.3 雙前導下劃線：當命名類屬性，調用時名稱改編。

2.2.4 前導和後置都是雙下劃線（不要建立這樣的名字）：存在于使用者控制的命名空間的“神奇”的對象或屬性：

__init__，__import__或__file__

2.2 函數、方法、常量名

函數的命名規則 主要用來可調用的。

小寫字母，必要時單詞用下劃線分開以提高可讀性，非公開的私有方法在前面加一個下劃線。

在接口被記錄并且主要用作調用的情況下，用函數的命名規則來代替類名的命名規則。

注意内置名有一個單獨的規則：大多數的内置名是一個單詞（或兩個單詞一起），首字母大寫字元串的規則僅用于異常名和内置常量。

常量大寫，必要時用下劃線隔開。

2.3 變量命名

first_word = "hello world"

變量名盡量小寫，多個單詞之間用下劃線隔開。

2.3.1 單字元變量命名

不要使用字元‘O’（大寫字母oh），‘l’（小寫字母el）和‘I’（大寫字母eye）作為單字元變量名。（你應該一眼看不出來後兩個有什麼差別），當想使用‘l’時，用‘L’代替。

2.3.2 全局變量命名

子產品設計為通過from M import *來使用，應使用__all__機制防止導出全局變量，或使用加字首的舊規則，為全局變量加下劃線（可能你像表明這些全局變量是“非公開子產品”）。

2.3.3 類型變量名

首字母大寫，并且盡量短

from typing import TypeVar

VT_co = TypeVar('VT_co', covariant=True)
KT_contra = TypeVar('KT_contra', contravariant=True)
           

2.3.4 執行個體變量名

采用函數命名規則：小寫字母，必要時單詞用下劃線分開以提高可讀性。

僅為非公開的私有執行個體變量使用一個前導下劃線。

為了避免和子類命名沖突，使用兩個前導下劃線調用Python的名稱改編規則：如果類Foo有一個屬性名為__a，通過Foo.__a不能通路。（可以通過調用Foo._Foo__a來通路。）

通常，兩個前導下劃線僅用來避免與子類的屬性名沖突。

2.3 子產品、包、類名

子產品名應該短，所有的字母小寫，可以在子產品名中使用下劃線來提高可讀性。

包名也應該短，所有的字母小寫，不鼓勵使用下劃線。

類名通常使用首字母大寫字元串的規則，私有類可用一個下劃組開頭。

3.注釋

如果可以，盡量用英文寫注釋，除非你120%的确定，所有看你注釋的人都會中文。

# Sure, I'm sure

當代碼修改時，始終優先更新注釋！

同代碼相沖突的注釋比沒有注釋更差。

如果注釋很短，末尾可以不加句号。

注釋塊通常适用于一些緊跟其後的代碼，并且那些代碼應使用相同級别的縮進。注釋塊的每行以一個#和一個空格開始（除非注釋裡面的文本有縮進）。

注釋塊内的段落之間由僅包含#的行隔開。

行内注釋就是注釋和代碼在同一行，它與代碼之間至少用兩個空格隔開。并且它以#和一個空格開始。

如果行内注釋指出的是顯而易見，那麼它就是不必要的：

x = x + 1 # Increment x

但有時，這樣是有用的：

x = x + 1 # Compensate for border

4.換行

限制所有行最多79個字元。

文檔字元串或注釋中，行的長度限制在72個字元。

反斜杠可用于換行

如果有二進制操作符+、- 等，一般在其之前換行

# 反斜杠用于換行
with open('/path/to/some/file/you/want/to/read') as file_1, \
     open('/path/to/some/file/being/written', 'w') as file_2:
    file_2.write(file_1.read())

#在二進制操作符之前換行
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)
           

5.空行與空格

5.1 空行

頂級函數和類的定義之間有兩行空行。

類内部的函數定義之間有一行空行。

額外的空行用來（謹慎地）分離相關的功能組。

相關的行（例如：一組虛拟實作）之間不使用空行。

5.2 空格

在類似這樣的二進制操作符兩邊加一個空格，但不要多加：(==, <, !=, >=, in, is, and, or, not,+=)

second_word = "hello world"

句尾不要加空格，如果 \ 後面跟了一個空格，它就不是一個有效的續行符了。

當=符号用于訓示關鍵字參數或預設參數值時，它周圍不要使用空格。

但如果參數既有注釋又有預設值，在等号兩邊增加一個空格。

def complex(real, imag=0.0):
    return magic(r=real, i=imag)
           

緊挨着括号，或是逗号、分号、冒号前的，不要使用空格。

spam(ham[1], {eggs: 2})

foo = (0,)

if x == 4: print x, y; x, y = y, x
           

不要在緊挨着左括号之前，函數調用的參數清單的開始處、索引或切片開始的左括号之前加上空格，或是為了與另外的指派操作符對齊，而加上不止一個空格。

Yes: spam(1)
No:  spam (1)
Yes: dct['key'] = lst[index]
No:  dct ['key'] = lst [index]

# yes：
x = 1
y = 2
long_variable = 3

# no:
x             = 1
y             = 2
long_variable = 3
           

在切片中冒号像一個二進制操作符，冒号兩側的有相等數量空格（把它看作最低優先級的操作符）。在一個擴充切片中，兩個冒号必須有相等數量的空格。例外：當一個切片參數被省略時，該空格被省略。

ham[1:9], ham[1:9:3], ham[:9:3], ham[1::3], ham[1:9:]
ham[lower:upper], ham[lower:upper:], ham[lower::step]
ham[lower+offset : upper+offset]
ham[: upper_fn(x) : step_fn(x)], ham[:: step_fn(x)]
ham[lower + offset : upper + offset]
           

6.縮進

每級縮進使用4個空格（pycham中的一個TAB）。

連續行應該對齊折疊元素。

空格是縮進方法的首選。

制表符僅用于與已經用制表符做縮進的代碼保持一緻。

Python3不允許混用制表符和空格來縮進。

# 這裡第2、3行縮進更多加以差別
def long_function_name(
        var_one,var_two,var_three,
        var_four):
    print(var_four)

# 保持對齊
fun = long_function_name("var_one", "var_two",
                       "var_three","var_four")
                       
# 懸挂縮進不一定4個空格
fun = long_function_name(
    "var_one", "var_two",
    "var_three","var_four")

# if 加開括号,可以沒有額外縮進
if(this_is_one_thing and
   that_is_another_thing):
   do_something()

# 條件接續行,也可以額外縮進
if(this_is_one_thing
        and that_is_another_thing):
   do_something()

# 大、中、小結束括号
list = [
    1,2,3,
    4,5,6,
    ]
    
# 或是這樣
list = [
    1,2,3,
    4,5,6
]

           

7.字元串與尾部逗号

7.1 字元串

Python中，單引号字元串和雙引号字元串是一樣的。本PEP不建議如此。建議選擇一條規則并堅持下去。當一個字元串包含單引号字元或雙引号字元時，使用另一種字元串引号來避免字元串中使用反斜杠，提高可讀性。

7.2 尾部逗号

尾部逗号通常都是可選的，除了一些強制的場景，比如元組在隻有一個元素的時候需要一個尾部逗号。（一個元素的元組一定要加逗号）

為了代碼更加清晰，元組隻有一個元素時請務必用括号括起來（文法上沒有強制要求）。

當尾部逗号不是必須時，如果你用了版本控制系統那麼它将很有用。當清單元素、參數、導入項未來可能不斷增加時，留一個尾部逗号是一個很好的選擇。

通常的用法是（比如清單）每個元素獨占一行，然後尾部都有逗号，在最後一個元素的下一行寫閉标簽。如果你的資料結構都是寫在同一行的，就沒有必要保留尾部逗号了。

# 注意，這裡如果不加逗号，表示一個元素，而不是元組！
FILES = ('setup.cfg',)

FILES = 'setup.cfg',

FILES = [
    'setup.cfg',
    'tox.ini',
    ]
initialize(FILES,
           error=True,
           )
           

更詳細的情況請進入開頭連結檢視。