一、簡明概述
1. 編碼
- 如無特殊情況, 文件一律使用 UTF-8 編碼
- 如無特殊情況, 文件頭部必須加入#--coding:utf-8--標識
2. 代碼格式
2.1 縮進
- 統一使用 4 個空格進行縮進
2.2 行寬
每行代碼儘量不超過 80 個字符(在特殊情況下可以略微超過 80 ,但最長不得超過 120)
理由:
- 這在查看 side-by-side 的 diff 時很有幫助
- 方便在控制檯下查看代碼
- 太長可能是設計有缺陷
2.3 引號
簡單說,自然語言使用雙引號,機器標示使用單引號,因此 代碼裏 多數應該使用 單引號
- 自然語言 使用雙引號 “…”
- 機器標識 使用單引號 ‘…’
- 正則表達式 使用原生的雙引號 r"…"
- 文檔字符串 (docstring) 使用三個雙引號 “”"…"""
2.4 空行
- 模塊級函數和類定義之間空兩行;
- 類成員函數之間空一行;
- 可以使用多個空行分隔多組相關的函數
- 函數中可以使用空行分隔出邏輯相關的代碼
class A:
def __init__(self):
pass
def hello(self):
pass
def main():
pass
3. import 語句
- import 語句應該分行書寫
# 正確的寫法
import os
import sys
# 不推薦的寫法
import sys,os
# 正確的寫法
from subprocess import Popen, PIPE
- import 語句應該使用 absolute import
# 正確的寫法
from foo.bar import Bar
# 不推薦的寫法
from ..bar import Bar
- import語句應該放在文件頭部,置於模塊說明及docstring之後,於全局變量之前;
- import語句應該按照順序排列,每組之間用一個空行分隔
import os
import sys
import msgpack
import zmq
import foo
- 導入其他模塊的類定義時,可以使用相對導入
from myclass import MyClass
- 如果發生命名衝突,則可使用命名空間
import bar
import foo.bar
bar.Bar()
foo.bar.Bar()
4. 空格
- 在二元運算符兩邊各空一格[=,-,+=,==,>,in,is not, and]:
# 正確的寫法
i = i + 1
submitted += 1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)
# 不推薦的寫法
i=i+1
submitted +=1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)
- 函數的參數列表中,,之後要有空格
# 正確的寫法
def complex(real, imag):
pass
# 不推薦的寫法
def complex(real,imag):
pass
- 函數的參數列表中,默認值等號兩邊不要添加空格
# 正確的寫法
def complex(real, imag=0.0):
pass
# 不推薦的寫法
def complex(real, imag = 0.0):
pass
- 左括號之後,右括號之前不要加多餘的空格
# 正確的寫法
spam(ham[1], {eggs: 2})
# 不推薦的寫法
spam( ham[1], { eggs : 2 } )
- 字典對象的左括號之前不要多餘的空格
# 正確的寫法
dict['key'] = list[index]
# 不推薦的寫法
dict ['key'] = list [index]
- 不要爲對齊賦值語句而使用的額外空格
# 正確的寫法
x = 1
y = 2
long_variable = 3
# 不推薦的寫法
x = 1
y = 2
long_variable = 3
5. 換行
Python 支持括號內的換行。這時有兩種情況。
1)第二行縮進到括號的起始處
foo = long_function_name(var_one, var_two,
var_three, var_four)
2)第二行縮進 4 個空格,適用於起始括號就換行的情形
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)
- 使用反斜槓\換行,二元運算符+ .等應出現在行末;長字符串也可以用此法換行
session.query(MyTable).\
filter_by(id=1).\
one()
print 'Hello, '\
'%s %s!' %\
('Harry', 'Potter')
- 禁止複合語句,即一行中包含多個語句:
# 正確的寫法
do_first()
do_second()
do_third()
# 不推薦的寫法
do_first();do_second();do_third();
- if/for/while一定要換行:
# 正確的寫法
if foo == 'blah':
do_blah_thing()
# 不推薦的寫法
if foo == 'blah': do_blash_thing()
6. docstring
docstring 的規範中最其本的兩點:
a. 所有的公共模塊、函數、類、方法,都應該寫 docstring 。私有方法不一定需要,但應該在 def 後提供一個塊註釋來說明。
b. docstring 的結束"""應該獨佔一行,除非此 docstring 只有一行。
"""Return a foobar
Optional plotz says to frobnicate the bizbaz first.
"""
"""Oneline docstring"""