一器钟、簡明概述
1、編碼
- 如無特殊情況, 文件一律使用 UTF-8 編碼
- 如無特殊情況, 文件頭部必須加入
#-*-coding:utf-8-*-標(biāo)識
2妙蔗、代碼格式
2.1傲霸、縮進(jìn)
- 統(tǒng)一使用 4 個空格進(jìn)行縮進(jìn)
2.2、行寬
每行代碼盡量不超過 80 個字符(在特殊情況下可以略微超過 80 眉反，但最長不得超過 120)
理由：
- 這在查看 side-by-side 的 diff 時很有幫助
- 方便在控制臺下查看代碼
- 太長可能是設(shè)計有缺陷
2.3昙啄、引號
簡單說，自然語言使用雙引號寸五，機器標(biāo)示使用單引號梳凛，因此 代碼里 多數(shù)應(yīng)該使用 單引號
-
自然語言 使用雙引號
"..."
例如錯誤信息；很多情況還是 unicode梳杏，使用u"你好世界" -
機器標(biāo)識 使用單引號
'...'
例如 dict 里的 key -
正則表達(dá)式 使用原生的雙引號
r"..." -
文檔字符串 (docstring) 使用三個雙引號
"""......"""
2.4韧拒、空行
- 模塊級函數(shù)和類定義之間空兩行；
- 類成員函數(shù)之間空一行十性；
class A:
def __init__(self):
pass
def hello(self):
pass
def main():
pass
- 可以使用多個空行分隔多組相關(guān)的函數(shù)
- 函數(shù)中可以使用空行分隔出邏輯相關(guān)的代碼
3叛溢、import 語句
- import 語句應(yīng)該分行書寫
# 正確的寫法
import os
import sys
# 不推薦的寫法
import sys,os
# 正確的寫法
from subprocess import Popen, PIPE
- import語句應(yīng)該使用 absolute import
# 正確的寫法
from foo.bar import Bar
# 不推薦的寫法
from ..bar import Bar
- import語句應(yīng)該放在文件頭部，置于模塊說明及docstring之后劲适，于全局變量之前楷掉；
- import語句應(yīng)該按照順序排列，每組之間用一個空行分隔
import os
import sys
import msgpack
import zmq
import foo
- 導(dǎo)入其他模塊的類定義時霞势，可以使用相對導(dǎo)入
from myclass import MyClass
- 如果發(fā)生命名沖突烹植，則可使用命名空間
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)
- 函數(shù)的參數(shù)列表中，
,之后要有空格
# 正確的寫法
def complex(real, imag):
pass
# 不推薦的寫法
def complex(real,imag):
pass
- 函數(shù)的參數(shù)列表中草雕，默認(rèn)值等號兩邊不要添加空格
# 正確的寫法
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 支持括號內(nèi)的換行促绵。這時有兩種情況攒庵。
- 第二行縮進(jìn)到括號的起始處
foo = long_function_name(var_one, var_two,
var_three, var_four)
- 第二行縮進(jìn) 4 個空格，適用于起始括號就換行的情形
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)
使用反斜杠\換行败晴，二元運算符+ .等應(yīng)出現(xiàn)在行末浓冒；長字符串也可以用此法換行
session.query(MyTable).\
filter_by(id=1).\
one()
print 'Hello, '\
'%s %s!' %\
('Harry', 'Potter')
禁止復(fù)合語句，即一行中包含多個語句：
# 正確的寫法
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 的規(guī)范中最其本的兩點：
- 所有的公共模塊稳懒、函數(shù)、類慢味、方法场梆，都應(yīng)該寫 docstring 。私有方法不一定需要纯路，但應(yīng)該在 def 后提供一個塊注釋來說明或油。
- docstring 的結(jié)束"""應(yīng)該獨占一行，除非此 docstring 只有一行驰唬。
"""Return a foobar
Optional plotz says to frobnicate the bizbaz first.
"""
"""Oneline docstring"""
二顶岸、注釋
1、注釋
1.1叫编、塊注釋
“#”號后空一格辖佣，段落件用空行分開（同樣需要“#”號）
# 塊注釋
# 塊注釋
#
# 塊注釋
# 塊注釋
1.2、行注釋
至少使用兩個空格和語句分開搓逾，注意不要使用無意義的注釋
# 正確的寫法
x = x + 1 # 邊框加粗一個像素
# 不推薦的寫法(無意義的注釋)
x = x + 1 # x加1
1.3卷谈、建議
在代碼的關(guān)鍵部分(或比較復(fù)雜的地方), 能寫注釋的要盡量寫注釋
比較重要的注釋段, 使用多個等號隔開, 可以更加醒目, 突出重要性
app = create_app(name, options)
# =====================================
# 請勿在此處添加 get post等app路由行為 !!!
# =====================================
if __name__ == '__main__':
app.run()
2、文檔注釋（Docstring）
作為文檔的Docstring一般出現(xiàn)在模塊頭部霞篡、函數(shù)和類的頭部世蔗，這樣在python中可以通過對象的__doc__對象獲取文檔.
編輯器和IDE也可以根據(jù)Docstring給出自動提示.
- 文檔注釋以 """ 開頭和結(jié)尾, 首行不換行, 如有多行, 末行必需換行, 以下是Google的docstring風(fēng)格示例
# -*- 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.
"""
- 不要在文檔注釋復(fù)制函數(shù)定義原型, 而是具體描述其具體內(nèi)容, 解釋具體參數(shù)和返回值等
# 不推薦的寫法(不要寫函數(shù)原型等廢話)
def function(a, b):
"""function(a, b) -> list"""
... ...
# 正確的寫法
def function(a, b):
"""計算并返回a到b范圍內(nèi)數(shù)據(jù)的平均值"""
... ...
- 對函數(shù)參數(shù)、返回值等的說明采用numpy標(biāo)準(zhǔn), 如下所示
def func(arg1, arg2):
"""在這里寫函數(shù)的一句話總結(jié)(如: 計算平均值).
這里是具體描述.
參數(shù)
----------
arg1 : int
arg1的具體描述
arg2 : int
arg2的具體描述
返回值
-------
int
返回值的具體描述
參看
--------
otherfunc : 其它關(guān)聯(lián)函數(shù)等...
示例
--------
示例使用doctest格式, 在`>>>`后的代碼可以被文檔測試工具作為測試用例自動運行
>>> a=[1,2,3]
>>> print [x + 3 for x in a]
[4, 5, 6]
"""
文檔注釋不限于中英文, 但不要中英文混用
文檔注釋不是越長越好, 通常一兩句話能把情況說清楚即可
模塊寇损、公有類凸郑、公有方法, 能寫文檔注釋的, 應(yīng)該盡量寫文檔注釋
三裳食、命名規(guī)范
1矛市、模塊
- 模塊盡量使用小寫命名，首字母保持小寫诲祸，盡量不要用下劃線(除非多個單詞浊吏，且數(shù)量不多的情況)
# 正確的模塊名
import decoder
import html_parser
# 不推薦的模塊名
import Decoder
2而昨、類名
- 類名使用駝峰(CamelCase)命名風(fēng)格，首字母大寫找田，私有類可用一個下劃線開頭
class Farm():
pass
class AnimalFarm(Farm):
pass
class _PrivateFarm(Farm):
pass
- 將相關(guān)的類和頂級函數(shù)放在同一個模塊里. 不像Java, 沒必要限制一個類一個模塊.
3歌憨、函數(shù)
- 函數(shù)名一律小寫，如有多個單詞墩衙，用下劃線隔開
def run():
pass
def run_with_env():
pass
- 私有函數(shù)在函數(shù)前加一個下劃線_
class Person():
def _private_func():
pass
4务嫡、變量名
- 變量名盡量小寫, 如有多個單詞，用下劃線隔開
if __name__ == '__main__':
count = 0
school_name = ''
- 常量采用全大寫漆改，如有多個單詞心铃，使用下劃線隔開
MAX_CLIENT = 100
MAX_CONNECTION = 1000
CONNECTION_TIMEOUT = 600
5、常量
- 常量使用以下劃線分隔的大寫命名
MAX_OVERFLOW = 100
Class FooBar:
def foo_bar(self, print_):
print(print_)
