http://www.imooc.com/article/19184?block_id=tuijian_wz#child_5_1

Python程式碼規範和命名規範

前言

Python 學習之旅，先來看看 Python 的程式碼規範，讓自己先有個意識，而且在往後的學習中慢慢養成習慣

目錄

一、簡明概述

1、編碼

• 如無特殊情況, 檔案一律使用 UTF-8 編碼
• 如無特殊情況, 檔案頭部必須加入#-*-coding:utf-8-*-標識

2、程式碼格式

2.1、縮排

• 統一使用 4 個空格進行縮排

2.2、行寬

每行程式碼儘量不超過 80 個字元(在特殊情況下可以略微超過 80 ，但最長不得超過 120)

理由：

• 這在檢視 side-by-side 的 diff 時很有幫助
• 方便在控制檯下檢視程式碼
• 太長可能是設計有缺陷

2.3、引號

簡單說，自然語言使用雙引號，機器標示使用單引號，因此 程式碼裡 多數應該使用 單引號

• 自然語言 使用雙引號 "..."
  例如錯誤資訊；很多情況還是 unicode，使用u"你好世界"
• 機器標識 使用單引號 '...'
  例如 dict 裡的 key
• 正則表示式 使用原生的雙引號 r"..."
• 文件字串 (docstring)
  使用三個雙引號 """......"""

2.4、空行

• 模組級函式和類定義之間空兩行；
• 類成員函式之間空一行；

1. class A:

2.  

3. def __init__(self):

4. pass

5.  

6. def hello(self):

7. pass

8.  

9. def main():

10. pass

• 可以使用多個空行分隔多組相關的函式
• 函式中可以使用空行分隔出邏輯相關的程式碼

2.5、編碼

• 檔案使用 UTF-8 編碼
• 檔案頭部加入#-*-conding:utf-8-*-標識

3、import 語句

• import 語句應該分行書寫

1. # 正確的寫法

2. import os

3. import sys

4.  

5. # 不推薦的寫法

6. import sys,os

7.  

8. # 正確的寫法

9. from subprocess import Popen, PIPE

• import語句應該使用 absolute import

1. # 正確的寫法

2. from foo.bar import Bar

3.  

4. # 不推薦的寫法

5. from ..bar import Bar

• import語句應該放在檔案頭部，置於模組說明及docstring之後，於全域性變數之前；
• import語句應該按照順序排列，每組之間用一個空行分隔

1. import os

2. import sys

3.  

4. import msgpack

5. import zmq

6.  

7. import foo

• 匯入其他模組的類定義時，可以使用相對匯入

from myclass import MyClass

• 如果發生命名衝突，則可使用名稱空間

1. import bar

2. import foo.bar

3.  

4. bar.Bar()

5. foo.bar.Bar()

4、空格

• 在二元運算子兩邊各空一格[=,-,+=,==,>,in,is not, and]:

1. # 正確的寫法

2. i = i + 1

3. submitted += 1

4. x = x * 2 - 1

5. hypot2 = x * x + y * y

6. c = (a + b) * (a - b)

7.  

8. # 不推薦的寫法

9. i=i+1

10. submitted +=1

11. x = x*2 - 1

12. hypot2 = x*x + y*y

13. c = (a+b) * (a-b)

• 函式的引數列表中，,之後要有空格

1. # 正確的寫法

2. def complex(real, imag):

3. pass

4.  

5. # 不推薦的寫法

6. def complex(real,imag):

7. pass

• 函式的引數列表中，預設值等號兩邊不要新增空格

1. # 正確的寫法

2. def complex(real, imag=0.0):

3. pass

4.  

5. # 不推薦的寫法

6. def complex(real, imag = 0.0):

7. pass

• 左括號之後，右括號之前不要加多餘的空格

1. # 正確的寫法

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

3.  

4. # 不推薦的寫法

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

• 字典物件的左括號之前不要多餘的空格

1. # 正確的寫法

2. dict['key'] = list[index]

3.  

4. # 不推薦的寫法

5. dict ['key'] = list [index]

• 不要為對齊賦值語句而使用的額外空格

1. # 正確的寫法

2. x = 1

3. y = 2

4. long_variable = 3

5.  

6. # 不推薦的寫法

7. x = 1

8. y = 2

9. long_variable = 3

5、換行

Python 支援括號內的換行。這時有兩種情況。

1) 第二行縮排到括號的起始處

1. foo = long_function_name(var_one, var_two,

2. var_three, var_four)

2) 第二行縮排 4 個空格，適用於起始括號就換行的情形

1. def long_function_name(

2. var_one, var_two, var_three,

3. var_four):

4. print(var_one)

使用反斜槓\換行，二元運算子+ .等應出現在行末；長字串也可以用此法換行

1. session.query(MyTable).\

2. filter_by(id=1).\

3. one()

4.  

5. print 'Hello, '\

6. '%s %s!' %\

7. ('Harry', 'Potter')

禁止複合語句，即一行中包含多個語句：

1. # 正確的寫法

2. do_first()

3. do_second()

4. do_third()

5.  

6. # 不推薦的寫法

7. do_first();do_second();do_third();

if/for/while一定要換行：

1. # 正確的寫法

2. if foo == 'blah':

3. do_blah_thing()

4.  

5. # 不推薦的寫法

6. if foo == 'blah': do_blash_thing()

6、docstring

docstring 的規範中最其本的兩點：

1. 所有的公共模組、函式、類、方法，都應該寫 docstring 。私有方法不一定需要，但應該在 def 後提供一個塊註釋來說明。
2. docstring 的結束"""應該獨佔一行，除非此 docstring 只有一行。

1. """Return a foobar

2. Optional plotz says to frobnicate the bizbaz first.

3. """

4.  

5. """Oneline docstring"""

二、註釋

1、註釋

1.1、塊註釋

“#”號後空一格，段落件用空行分開（同樣需要“#”號）

1. # 塊註釋

2. # 塊註釋

3. #

4. # 塊註釋

5. # 塊註釋

1.2、行註釋

至少使用兩個空格和語句分開，注意不要使用無意義的註釋

1. # 正確的寫法

2. x = x + 1 # 邊框加粗一個畫素

3.  

4. # 不推薦的寫法(無意義的註釋)

5. x = x + 1 # x加1

1.3、建議

• 在程式碼的關鍵部分(或比較複雜的地方), 能寫註釋的要儘量寫註釋

• 比較重要的註釋段, 使用多個等號隔開, 可以更加醒目, 突出重要性

1. app = create_app(name, options)

2.  

3. # =====================================

4. # 請勿在此處新增 get post等app路由行為 !!!

5. # =====================================

6.  

7. if __name__ == '__main__':

8. app.run()

2、文件註釋（Docstring）

作為文件的Docstring一般出現在模組頭部、函式和類的頭部，這樣在python中可以通過物件的__doc__物件獲取文件.
編輯器和IDE也可以根據Docstring給出自動提示.

• 文件註釋以 """ 開頭和結尾, 首行不換行, 如有多行, 末行必需換行, 以下是Google的docstring風格示例

1. # -*- coding: utf-8 -*-

2. """Example docstrings.

3.  

4. This module demonstrates documentation as specified by the `Google Python

5. Style Guide`_. Docstrings may extend over multiple lines. Sections are created

6. with a section header and a colon followed by a block of indented text.

7.  

8. Example:

9. Examples can be given using either the ``Example`` or ``Examples``

10. sections. Sections support any reStructuredText formatting, including

11. literal blocks::

12.  

13. $ python example_google.py

14.  

15. Section breaks are created by resuming unindented text. Section breaks

16. are also implicitly created anytime a new section starts.

17. """

• 不要在文件註釋複製函式定義原型, 而是具體描述其具體內容, 解釋具體引數和返回值等

1. # 不推薦的寫法(不要寫函式原型等廢話)

2. def function(a, b):

3. """function(a, b) -> list"""

4. ... ...

5.  

6. # 正確的寫法

7. def function(a, b):

8. """計算並返回a到b範圍內資料的平均值"""

9. ... ...

• 對函式引數、返回值等的說明採用numpy標準, 如下所示

1. def func(arg1, arg2):

2. """在這裡寫函式的一句話總結(如: 計算平均值).

3.  

4. 這裡是具體描述.

5.  

6. 引數

7. ----------

8. arg1 : int

9. arg1的具體描述

10. arg2 : int

11. arg2的具體描述

12.  

13. 返回值

14. -------

15. int

16. 返回值的具體描述

17.  

18. 參看

19. --------

20. otherfunc : 其它關聯函式等...

21.  

22. 示例

23. --------

24. 示例使用doctest格式, 在`>>>`後的程式碼可以被文件測試工具作為測試用例自動執行

25.  

26. >>> a=[1,2,3]

27. >>> print [x + 3 for x in a]

28. [4, 5, 6]

29. """

• 文件註釋不限於中英文, 但不要中英文混用

• 文件註釋不是越長越好, 通常一兩句話能把情況說清楚即可

• 模組、公有類、公有方法, 能寫文件註釋的, 應該儘量寫文件註釋

三、命名規範

1、模組

• 模組儘量使用小寫命名，首字母保持小寫，儘量不要用下劃線(除非多個單詞，且數量不多的情況)

1. # 正確的模組名

2. import decoder

3. import html_parser

4.  

5. # 不推薦的模組名

6. import Decoder

2、類名

• 類名使用駝峰(CamelCase)命名風格，首字母大寫，私有類可用一個下劃線開頭

1. class Farm():

2. pass

3.  

4. class AnimalFarm(Farm):

5. pass

6.  

7. class _PrivateFarm(Farm):

8. pass

• 將相關的類和頂級函式放在同一個模組裡. 不像Java, 沒必要限制一個類一個模組.

3、函式

• 函式名一律小寫，如有多個單詞，用下劃線隔開

1. def run():

2. pass

3.  

4. def run_with_env():

5. pass

• 私有函式在函式前加一個下劃線_

1. class Person():

2.  

3. def _private_func():

4. pass

4、變數名

• 變數名儘量小寫, 如有多個單詞，用下劃線隔開

1. if __name__ == '__main__':

2. count = 0

3. school_name = ''

• 常量採用全大寫，如有多個單詞，使用下劃線隔開

1. MAX_CLIENT = 100

2. MAX_CONNECTION = 1000

3. CONNECTION_TIMEOUT = 600

5、常量

• 常量使用以下劃線分隔的大寫命名

1. MAX_OVERFLOW = 100

2.  

3. Class FooBar:

4.  

5. def foo_bar(self, print_):

6. print(print_)