前言
Python 學習之旅，先來看看 Python 的代碼規範，讓本身先有個意識，並且在日後的學習中慢慢養成習慣html
目錄
- 如無特殊狀況, 文件一概使用 UTF-8 編碼
- 如無特殊狀況, 文件頭部必須加入
#-*-coding:utf-8-*-標識
2.一、縮進
- 統一使用 4 個空格進行縮進
2.二、行寬
每行代碼儘可能不超過 80 個字符(在特殊狀況下能夠略微超過 80 ，但最長不得超過 120)python
理由：web
- 這在查看 side-by-side 的 diff 時頗有幫助
- 方便在控制檯下查看代碼
- 太長多是設計有缺陷
2.三、引號
簡單說，天然語言使用雙引號，機器標示使用單引號，所以 代碼裏 多數應該使用 單引號正則表達式
- 天然語言 使用雙引號
"..."
例如錯誤信息；不少狀況仍是 unicode，使用u"你好世界" - 機器標識 使用單引號
'...'
例如 dict 裏的 key - 正則表達式 使用原生的雙引號
r"..." - 文檔字符串 (docstring) 使用三個雙引號
"""......"""
2.四、空行
- 模塊級函數和類定義之間空兩行；
- 類成員函數之間空一行；
-
class
A
:
-
-
def
__init__
(
self
):
-
pass
-
-
def
hello
(
self
):
-
pass
-
-
def
main
():
-
pass
- 可使用多個空行分隔多組相關的函數
- 函數中可使用空行分隔出邏輯相關的代碼
2.五、編碼
- 文件使用 UTF-8 編碼
- 文件頭部加入
#-*-conding:utf-8-*-標識
- 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
()
四、空格
- 在二元運算符兩邊各空一格
[=,-,+=,==,>,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
五、換行
Python 支持括號內的換行。這時有兩種狀況。session
1) 第二行縮進到括號的起始處app
-
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
)
使用反斜槓\換行，二元運算符+ .等應出如今行末；長字符串也能夠用此法換行ide
-
session
.
query
(
MyTable
).
\
-
filter_by
(
id
=
1
).
\
-
one
()
-
-
print
'Hello, '
\
-
'%s %s!'
%
\
-
(
'Harry'
,
'Potter'
)
禁止複合語句，即一行中包含多個語句：svg
-
# 正確的寫法
-
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
()
六、docstring
docstring 的規範中最其本的兩點：
- 全部的公共模塊、函數、類、方法，都應該寫 docstring 。私有方法不必定須要，但應該在 def 後提供一個塊註釋來講明。
- docstring 的結束」「」應該獨佔一行，除非此 docstring 只有一行。
-
"""Return a foobar
-
Optional plotz says to frobnicate the bizbaz first.
-
"""
-
-
"""Oneline docstring"""
2、註釋
一、註釋
1.一、塊註釋
「#」號後空一格，段落件用空行分開（一樣須要「#」號）
-
# 塊註釋
-
# 塊註釋
-
#
-
# 塊註釋
-
# 塊註釋
1.二、行註釋
至少使用兩個空格和語句分開，注意不要使用無心義的註釋
-
# 正確的寫法
-
x
=
x
+
1
# 邊框加粗一個像素
-
-
# 不推薦的寫法(無心義的註釋)
-
x
=
x
+
1
# x加1
1.三、建議
-
在代碼的關鍵部分(或比較複雜的地方), 能寫註釋的要儘可能寫註釋
- 比較重要的註釋段, 使用多個等號隔開, 能夠更加醒目, 突出重要性
-
app
=
create_app
(
name
,
options
)
-
-
# =====================================
-
# 請勿在此處添加 get post等app路由行爲 !!!
-
# =====================================
-
-
if
__name__
==
'__main__'
:
-
app
.
run
()
二、文檔註釋（Docstring）
做爲文檔的Docstring通常出如今模塊頭部、函數和類的頭部，這樣在python中能夠經過對象的__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]
-
"""
-
文檔註釋不限於中英文, 但不要中英文混用
-
文檔註釋不是越長越好, 一般一兩句話能把狀況說清楚便可
- 模塊、公有類、公有方法, 能寫文檔註釋的, 應該儘可能寫文檔註釋
- 模塊儘可能使用小寫命名，首字母保持小寫，儘可能不要用下劃線(除非多個單詞，且數量很少的狀況)
-
# 正確的模塊名
-
import
decoder
-
import
html_parser
-
-
# 不推薦的模塊名
-
import
Decoder
二、類名
- 類名使用駝峯(CamelCase)命名風格，首字母大寫，私有類可用一個下劃線開頭
-
class
Farm
():
-
pass
-
-
class
AnimalFarm
(
Farm
):
-
pass
-
-
class
_PrivateFarm
(
Farm
):
-
pass
- 將相關的類和頂級函數放在同一個模塊裏. 不像Java, 不必限制一個類一個模塊.
- 函數名一概小寫，若有多個單詞，用下劃線隔開
-
def
run
():
-
pass
-
-
def
run_with_env
():
-
pass
- 私有函數在函數前加一個下劃線_
-
class
Person
():
-
-
def
_private_func
():
-
pass
四、變量名
- 變量名儘可能小寫, 若有多個單詞，用下劃線隔開
-
if
__name__
==
'__main__'
:
-
count
=
0
-
school_name
=
''
- 常量採用全大寫，若有多個單詞，使用下劃線隔開
-
MAX_CLIENT
=
100
-
MAX_CONNECTION
=
1000
-
CONNECTION_TIMEOUT
=
600
五、常量
- 常量使用如下劃線分隔的大寫命名
-
MAX_OVERFLOW
=
100
-
-
Class
FooBar
:
-
-
def
foo_bar
(
self
,
print_
):
-
print
(
print_
)
</div>
</div>
</article>