目錄
一、簡明概述
1、編碼
- 如無特殊情況,文件一律使用
utf-8
編碼,即在文件頭部必須加入標識# -*- conding: utf-8 -*-
2、代碼格式
(1)縮進
- 統一使用 4 個空格進行縮進
(2)行寬
- 每行代碼儘量不要超過 80 個字符(在特殊情況下,可以略微超過 80,但最長不能超過 120 個字符)
理由:
- 方便查看
side-by-side
的diff
- 方便在控制檯下查看代碼
- 太長可能是設計有缺陷
(3)引號
自然語言使用雙引號,機器標示使用單引號,因此代碼裏多數情況下應該是使用單引號。
- 自然語言使用雙引號:例如錯誤信息等
- 機器標示使用單引號:例如
dict
中的key
- 正則表達式使用原生的雙引號:
r""
- 文檔字符串(
docstring
)使用三個雙引號
(4)空行
- 模塊級函數和類定義之間空兩行
- 類的成員函數之間空一行
class A:
def __init__(self):
pass
def hello_world(self):
pass
def main():
pass
- 可以使用多個空行分割多組相關的函數
- 函數中可以使用空行分割出邏輯相關的代碼
3、import
語句
import
語句應該分行書寫
# 正確的寫法
import os
import sys
# 不推薦的寫法
import os, sys
# 正確的寫法
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)
- 在一元前綴運算符後不加空格
if !flag:
pass
“:”
用在行尾時前後皆不加空格,如分枝、循環、函數和類定義語言
if flag:
pass
- 函數的參數列表中,
,
之後要有空格
# 正確的寫法
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、換行
Python3 支持括號內的換行。這時有兩種情況。
- 第二行縮進到括號的起始處
foo = long_function_name(var_one, var_two,
var_three, var_four)
- 第二行縮進 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
的規範中最其本的兩點:
- 所有的公共模塊、函數、類、方法,都應該寫
docstring
。私有方法不一定需要,但應該在def
後提供一個塊註釋來說明。 docstring
的結束"""
應該獨佔一行,除非此docstring
只有一行。
"""Return a foobar
Optional plotz says to frobnicate the bizbaz first.
"""
"""Oneline docstring"""
二、註釋
1、普通註釋
(1)塊註釋
“#”
號後空一格,段落件用空行分開(同樣需要“#”
號)
# 塊註釋
# 塊註釋
#
# 塊註釋
# 塊註釋
(2)行註釋
至少使用兩個空格和語句分開,注意不要使用無意義的註釋
# 正確的寫法
x = x + 1 # 邊框加粗一個像素
# 不推薦的寫法(無意義的註釋)
x = x + 1 # x加1
2、文檔註釋
作爲文檔的Docstring
一般出現在模塊頭部、函數和類的頭部,這樣在python3
中可以通過對象的__doc__
對象獲取文檔.
編輯器和IDE
也可以根據Docstring
給出自動提示.
- 文檔註釋以
"""
開頭和結尾, 首行不換行, 如有多行, 末行必需換行, 以下是Google
的docstring
風格示例
# -*- coding: utf-8 -*-
"""Example docstrings.
This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.
Example:
Examples can be given using either the ``Example`` or ``Examples``
sections. Sections support any reStructuredText formatting, including
literal blocks::
$ python example_google.py
Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.
"""
- 不要在文檔註釋複製函數定義原型, 而是具體描述其具體內容, 解釋具體參數和返回值等
# 不推薦的寫法(不要寫函數原型等廢話)
def function(a, b):
"""function(a, b) -> list"""
... ...
# 正確的寫法
def function(a, b):
"""計算並返回a到b範圍內數據的平均值"""
... ...
- 對函數參數、返回值等的說明採用
numpy
標準, 如下所示
def func(arg1, arg2):
"""在這裏寫函數的一句話總結(如: 計算平均值).
這裏是具體描述.
參數
----------
arg1 : int
arg1的具體描述
arg2 : int
arg2的具體描述
返回值
-------
int
返回值的具體描述
參看
--------
otherfunc : 其它關聯函數等...
示例
--------
示例使用doctest格式, 在`>>>`後的代碼可以被文檔測試工具作爲測試用例自動運行
>>> a=[1,2,3]
>>> print [x + 3 for x in a]
[4, 5, 6]
"""
- 文檔註釋不限於中英文, 但不要中英文混用
- 文檔註釋不是越長越好, 通常一兩句話能把情況說清楚即可
- 模塊、公有類、公有方法, 能寫文檔註釋的, 應該儘量寫文檔註釋
添加註釋的原則:
堅持適當註釋原則。對不存在技術難點的代碼堅持不註釋,對存在技術難點的代碼必須註釋。但與註釋不同,建議對每一個包、模塊、類、函數(方法)寫 docstrings,除非代碼一目瞭然,非常簡單。
三、命名規範
1、模塊
- 模塊儘量使用小寫命名,首字母保持小寫,儘量不要用下劃線(除非多個單詞,且數量不多的情況)
# 正確的模塊名
import decoder
import html_parser
# 不推薦的模塊名
import Decoder
2、類名
- 類名使用駝峯(
CamelCase
)命名風格,首字母大寫,私有類可用一個下劃線開頭
class Farm():
pass
class AnimalFarm(Farm):
pass
class _PrivateFarm(Farm):
pass
- 將相關的類和頂級函數放在同一個模塊裏. 不像
Java
, 沒必要限制一個類一個模塊.
3、函數
- 函數名一律小寫,如有多個單詞,用下劃線隔開
def run():
pass
def run_with_env():
pass
- 私有函數在函數前加一個下劃線_
class Person():
def _private_func():
pass
4、變量名
- 變量名儘量小寫, 如有多個單詞,用下劃線隔開
if __name__ == '__main__':
count = 0
school_name = ''
- 常量採用全大寫,如有多個單詞,使用下劃線隔開
MAX_CLIENT = 100
MAX_CONNECTION = 1000
CONNECTION_TIMEOUT = 600
5、包
包命名儘量短小,使用全部小寫的方式,不可以使用下劃線。
四、編碼建議
- 編碼中考慮到其他
python
實現的效率等問題,比如運算符‘+’
在CPython(Python)
中效率很高,都是Jython
中卻非常低,所以應該採用.join()
的方式。 - 儘可能使用
‘is’``‘is not’
取代‘==’
,比如if x is not None
要優於if x
。 - 使用基於類的異常,每個模塊或包都有自己的異常類,此異常類繼承自
Exception
。 - 異常中不要使用裸露的
except
,except
後跟具體的exceptions
。 - 異常中
try
的代碼儘可能少。 - 使用
startswith() and endswith()
代替切片進行序列前綴或後綴檢查。
參考文獻:
https://zhuanlan.zhihu.com/p/29143263
https://zhuanlan.zhihu.com/p/31212390
https://zhuanlan.zhihu.com/p/21270222