python常用規范

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_)

 

 參考鏈接：https://blog.csdn.net/warm77/article/details/78353632