python代碼規範

爲何要有代碼規範？

1.作哪一行都有高低級別之分，別寫一行代碼就被人鄙視了。
2.好的規範會造成好的編碼風格，看着熟悉、親切，心情好。
3.增長可讀性，易維護，提升工做效率。
4.遵循規範，代碼會本身寫代碼。
5.國家爲啥要有法律，就是爲了管理。

 

 

1、簡明概述

一、編碼

• 如無特殊狀況, 文件一概使用 UTF-8 編碼

• 如無特殊狀況, 文件頭部必須加入#-*-coding:utf-8-*-標識

二、代碼格式

2.一、縮進

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

2.二、行寬

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

理由：

• 這在查看 side-by-side 的 diff 時頗有幫助

• 方便在控制檯下查看代碼

• 太長多是設計有缺陷

2.三、引號

簡單說，天然語言使用雙引號，機器標示使用單引號，所以 代碼裏 多數應該使用 單引號

• 天然語言 使用雙引號 "..."

例如錯誤信息；不少狀況仍是 unicode，使用u"你好世界"

• 機器標識 使用單引號 '...'

例如 dict 裏的 key

• 正則表達式 使用原生的雙引號 r"..."

• 文檔字符串 (docstring) 使用三個雙引號 """......"""

2.四、空行

• 模塊級函數和類定義之間空兩行；

• 類成員函數之間空一行；

• 可使用多個空行分隔多組相關的函數

• 函數中可使用空行分隔出邏輯相關的代碼

2.五、編碼

• 文件使用 UTF-8 編碼

• 文件頭部加入 # -*-conding:utf-8-*- 標識

三、import 語句

• import 語句應該分行書寫

• import語句應該使用 absolute import

• import語句應該放在文件頭部，置於模塊說明及docstring以後，於全局變量以前；

• import語句應該按照順序排列，每組之間用一個空行分隔

• 導入其餘模塊的類定義時，可使用相對導入

• 若是發生命名衝突，則可以使用命名空間

四、空格

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

• 函數的參數列表中，,以後要有空格

• 函數的參數列表中，默認值等號兩邊不要添加空格

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

• 字典對象的左括號以前不要多餘的空格

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

五、換行

Python 支持括號內的換行。這時有兩種狀況。

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

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

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

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

if/for/while必定要換行：

六、docstring

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

1. 全部的公共模塊、函數、類、方法，都應該寫 docstring 。私有方法不必定須要，但應該在 def 後提供一個塊註釋來講明。

2. docstring 的結束」「」應該獨佔一行，除非此 docstring 只有一行。

 

2、註釋

一、註釋

1.一、塊註釋

「#」號後空一格，段落件用空行分開（一樣須要「#」號）

1.二、行註釋

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

1.三、建議

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

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

二、文檔註釋（Docstring）

做爲文檔的Docstring通常出如今模塊頭部、函數和類的頭部，這樣在python中能夠經過對象的__doc__對象獲取文檔.

編輯器和IDE也能夠根據Docstring給出自動提示.

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

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

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

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

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

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

 

3、命名規範

一、模塊

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

二、類名

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

• 將相關的類和頂級函數放在同一個模塊裏. 不像Java, 不必限制一個類一個模塊.

三、函數

四、變量名

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

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

五、常量

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

 

 

四. 主要命名規範
模塊名採用小寫字母而且如下劃線分隔單詞的形式；

包名應當簡短，使用全小寫，可是不要使用下劃線

類名採用以大寫字母開頭，而且以大寫字母分隔單詞的形式命名（駝峯式命名）；

全局或者類常量，所有使用大寫字母，而且如下劃線分隔單詞；其他變量命名則是採用所有小寫字母，而且如下劃線分隔單詞的形式命名。

以上的內容若是是內部的，則使用下劃線開頭命名。

類型

公共（全局）

內部

模塊名

lower_with_under

_ lower_with_under

包名

lowerwithoutunder

 

類名

CapWords

_ CapWords

異常名

CapWords

 

函數名

lower_with_under( )

_ lower_with_under( )

全局/類常量

CAPS_WITH_UNDER

_ CAPS_WITH_UNDER

全局/類變量

lower_with_under

_ lower_with_under

實例變量

lower_with_under

_ lower_with_under（單下劃線私有）

__lower_with_under（雙下劃線避免與子類衝突）

方法名

lower_with_under( )

_ lower_with_under()（單下劃線私有）

__lower_with_under()（雙下劃線避免與子類命名衝突）

函數/方法參數

lower_with_under

 

本地變量

lower_with_under

 

注：

一、from M import * 不會導入如下劃線開始的對象。

二、異常也是一個類，因此須要遵循類名規則。但若是你的異常確實是個錯誤的話，請使用Error前綴

三、函數與方法參數設置時，使用self做爲實例方法的第一個參數。使用cls做爲類方法的第一個參數。當函數的參數名與保留字衝突時，使用下劃線後綴（第二次提醒）。

四、方法名與實例變量設置時，在私有方法和實例變量前用單下劃線前綴。使用雙下劃線前綴來調用"name mangling"來避免與子類命名衝突。若是類Foo有個屬性叫__a，那麼它不能使用Foo.__a讀取，但仍然能夠Foo._Foo__a來讀取

五、應避免使用的命名：不要使用小寫的L、大寫的O、以及大寫的I做爲單字符變量名。__double_leading_and_trailing_underscore__：（雙下劃線開始和結束）存活在用戶控制命名空間的"magic"對象或屬性。例如__init__, __import__ 或 __file__。永遠不要起這樣的名字。