python代碼規範整理

規範參考源：

1.pep8（python代碼樣式規範）：中文文檔      http://www.javashuo.com/article/p-ssraagam-mm.html

2.pep257(python文檔字符串相關約定)：文檔地址    https://github.com/qiuxiang/pep/blob/master/peps/257.md

3.pep20(python的禪宗) ：文檔地址  https://www.python.org/dev/peps/pep-0020/

 

代碼樣式規範（pep8）：

一、行縮進：tap鍵（4個空格）

隱式行鏈接縮進：

1.對齊縮進

foo = long_function_name(var_one,var_two,
　　　　　　　　　　　　　　 var_three, var_four,var_five)

2.層級縮進

def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

3. \

with open('test1.txt','w') as f1, \
     open('test2.txt','w') as f2;
    f1.write('hello')
    f2.write('python')

2.單行字符限制：

1.全部行限制的最大字符數爲79；

2.沒有結構化限制的大塊文本（文檔字符或註釋）；

每行最大字符數限制在72，可根據須要調整，建議不超過100

3.空行：

頂級函數與類的定義之間有兩行空行。

類頂部的函數定義之間有一行空行。

4.源文件編碼方式：

python核心發佈的代碼中應該自始至終使用UTF-8（python2默認是ASCII編碼）

python3種不該有編碼聲明

5.註釋

與代碼相矛盾的註釋比沒有註釋還糟，當代嗎更改時，優先更新對應的註釋；

若是註釋很短，結尾句號能夠省略。塊註釋通常由一個完整的句子或多個段落組成，而且每句結束有句號，在句號結束的時候應該使用兩個空格

在非英語國家的python程序員，請使用英文寫註釋，除非你120%的確信你的代碼不會被使用其餘語言的人閱讀

行內註釋：

#與代碼間至少要有兩個空格分隔，註釋由#和一個空格開始。有節制地使用行內註釋

response=requests.get('https://www.baidu.com')  # 請求百度首頁

塊註釋

一般用於跟隨它們的某些或所有代碼，並縮進到與代碼相同的級別。塊註釋的每一行開頭使用一個#和一個空格（除非塊註釋內部縮進文本）。

塊註釋內部的段落一般只有一個#的空行分隔。

def add_num(a,b,c):
    # 此函數的做用爲打印a，b，c三個數相加之和，並返回
    #
    # 經過format進行格式化輸出結果
    print（'三個數相加的結果｛｝'.format(a+b+c)）

PEP257

文檔註釋（文檔說明）：PEP257描述了寫出好的文檔說明相關的約定。

文檔註釋應當使用：經常使用3個雙引號"""quotes"""來包裹

要爲全部的公共模塊，函數，類，以及方法編寫文檔說明。

非公共的方法沒有必要添加註釋文檔，可是應該有一個描述方法具體做用的註釋。這個註釋應該在def那一行以後

def get(url, params=None, **kwargs):
    r"""Sends a GET request.

    :param url: URL for the new :class:`Request` object.
    :param params: (optional) Dictionary, list of tuples or bytes to send
        in the query string for the :class:`Request`.
    :param \*\*kwargs: Optional arguments that ``request`` takes.
    :return: :class:`Response <Response>` object
    :rtype: requests.Response
    """

    kwargs.setdefault('allow_redirects', True)
    return request('get', url, params=params, **kwargs)

單行文檔註釋："""quote""" ，一個簡短的句子，引號和文字在同一行

多行文檔註釋：多行文檔字符串有一個摘要組成，就像一行文檔字符串，後跟一個空行，後面是更詳細的描述，多行文檔說明使用的結尾三引號應該自成一行

提取文檔註釋：對象的__doc__屬性

import requests
print(requests.__doc__)
print(requests.get.__doc__)

六、模塊和包相關規範

導入代碼位置：導入經常位於文件頂部，在文檔字符串（註釋）以後，在模塊的全局變量和常量以前

導入順序分組：

1.標準庫導入

2.相關的第三方庫導入

3.特定的本地應用/庫導入，

推薦:      import os
          import sys
不推薦:    import sys, os
容許：     from subprocess import Popen, PIPE
推薦絕對路徑：from mypkg.sibling import example
容許相對路徑：from . import sibling
            from .sibling import example

4.__all__ , __author__ , __version__ 等這樣的模塊級內置屬性，應該放在文檔字符串的後面，以及除from __future__ 以外的import表達式前面。

"""This is the example module.

This module does stuff.
"""

from __future__ import barry_as_FLUFL

__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'

import os
import sys

七、命名規範

變量命名

永遠不要使用字母‘l’（小寫的L），‘O’（大寫的O），或者‘I’（大寫的I）做爲單字符變量名。 
在有些字體裏，這些字符沒法和數字0和1區分，若是想用‘l’，用‘L’代替。

函數命名

函數名應該小寫，若是想提升可讀性能夠用下劃線分隔。 
大小寫混合僅在爲了兼容原來主要以大小寫混合風格的狀況下使用（好比 threading.py），保持向後兼容性。

包名或模塊名

模塊應該用簡短全小寫的名字，若是爲了提高可讀性，下劃線也是能夠用的。Python包名也應該使用簡短全小寫的名字，但不建議用下劃線。 

類名

類名通常使用首字母大寫的約定。 
在接口被文檔化而且主要被用於調用的狀況下，可使用函數的命名風格代替。 
注意，對於內置的變量命名有一個單獨的約定：大部份內置變量是單個單詞（或者兩個單詞鏈接在一塊兒），首字母大寫的命名法只用於異常名或者內部的常量。

 類裏面的函數與方法參數

始終要將 self 做爲實例方法的的第一個參數。 
始終要將 cls 做爲類靜態方法的第一個參數。 
若是函數的參數名和已有的關鍵詞衝突，在最後加單一下劃線比縮寫或隨意拼寫更好。所以 class_ 比 clss 更好。（也許最好用同義詞來避免這種衝突）

常量

常量一般定義在模塊級，經過下劃線分隔的全大寫字母命名。例如： MAX_OVERFLOW 和 TOTAL。

 

最後附上python之禪中文版：

優美勝於醜陋（Python 以編寫優美的代碼爲目標）

明瞭勝於晦澀（優美的代碼應當是明瞭的，命名規範，風格類似）

簡潔勝於複雜（優美的代碼應當是簡潔的，不要有複雜的內部實現）

複雜勝於凌亂（若是複雜不可避免，那代碼間也不能有難懂的關係，要保持接口簡潔）

扁平勝於嵌套（優美的代碼應當是扁平的，不能有太多的嵌套）

間隔勝於緊湊（優美的代碼有適當的間隔，不要奢望一行代碼解決問題）

可讀性很重要（優美的代碼是可讀的）

即使假借特例的實用性之名，也不可違背這些規則（這些規則至高無上）