Python代碼規範和命名規範

前言

Python 學習之旅，先來看看 Python 的代碼規範，讓本身先有個意識，並且在日後的學習中慢慢養成習慣

 

1、簡明概述

一、編碼

• 如無特殊狀況, 文件一概使用 UTF-8 編碼
• 如無特殊狀況, 文件頭部必須加入#-*-coding:utf-8-*-標識

二、代碼格式

2.一、縮進

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

2.二、行寬

每行代碼儘可能不超過 80 個字符(在特殊狀況下能夠略微超過 80 ，但最長不得超過 120)

理由：

• 這在查看 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 語句應該分行書寫

# 正確的寫法
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 支持括號內的換行。這時有兩種狀況。

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

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)

使用反斜槓\換行，二元運算符+ .等應出如今行末；長字符串也能夠用此法換行

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

六、docstring

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

1. 全部的公共模塊、函數、類、方法，都應該寫 docstring 。私有方法不必定須要，但應該在 def 後提供一個塊註釋來講明。
2. 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]
    """

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

• 文檔註釋不是越長越好, 一般一兩句話能把狀況說清楚便可

• 模塊、公有類、公有方法, 能寫文檔註釋的, 應該儘可能寫文檔註釋

 

3、命名規範

一、模塊

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

# 正確的模塊名
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_)