Python編碼規(guī)范

1、inf-qa python編碼規(guī)范修改記錄no 版本號修改內(nèi)容簡介修改日期修改人1v1.0全文2010-11-18 崔晶晶2 v1.1 增加 case 編碼規(guī)范2013-05-10 崔晶晶目錄inf-qa python 編碼規(guī)范 . 11. 介紹 . 31.1. 開發(fā)背景 . 31.2. 語言 . 31.2.1. 版本 . 31.3. 規(guī)范文檔 . 32. 一致性的建議. 33. 代碼的布局 . 33.1. 縮進 . 33.2. tab鍵還是空格 . 43.3. 行的最大長度. 43.4. 空行 . 43.5. 編碼 . 44. 導入 . 45. 空格 . 55.1. 其它建議 . 56. 注

2、釋 . 66.1 注釋塊 . 66.2 行內(nèi)注釋 . 67. 文檔化 . 78. 版本注解 . 79. 命名約定 . 79.1. 描述：命名風格. 79.2. 說明：命名約定. 89.2.1. 應(yīng)避免的名字. 89.2.2. 模塊名 . 89.2.3. 類名 . 89.2.4. 異常名 . 89.2.5. 全局變量名 . 89.2.6. 函數(shù)名 . 99.2.7. 方法名和實例變量名. 99.2.8. 繼承 . 910. 設(shè)計建議 . 911. demo . 10 12. the zen of python. 12 1. 介紹1.1.開發(fā)背景為了提高組內(nèi)自動化開發(fā)效率，避免重復開發(fā)，對組內(nèi)各模

3、塊已開發(fā)的自動化lib 庫、case 中常用的操作、以及其他工具的調(diào)用接口進行匯總，管理出dsqa 組內(nèi)自動化case開發(fā)的基礎(chǔ)庫。1.2.語言基礎(chǔ)庫采用python 開發(fā)。需要調(diào)用的相關(guān)二進制工具的地方，為降低開發(fā)成本，暫采用直接調(diào)該工具，封出python 方法接口。1.2.1. 版本python 版本較多，為避免上下版本的兼容性問題，開發(fā)采用統(tǒng)一版本。python 2.6.2/2.7.x 1.3.規(guī)范文檔為了方便維護、 他人閱讀使用，整理出該編碼規(guī)范文檔。請大家開發(fā)時遵循本規(guī)范進行更開發(fā)。本文檔參考自guido 的 python 風格指南一文. 并從 barrys style guide中

4、添加了部分內(nèi)容，以及我的個人建議。2. 一致性的建議整個項目的開發(fā)中，請盡量保持一致性，尤其是一個模塊或者一個函數(shù)中的一致性更為重要。因此存在這樣的一個問題：由于不同模塊的lib 庫開發(fā)人不同，編碼規(guī)范也可能不同，整合起來會顯得不夠“和諧”。還是希望各模塊lib 庫負責人做相應(yīng)的修改，盡量“和諧”。3. 代碼的布局3.1.縮進眾所周知， python 是通過縮進來進行代碼布局的。使用vi 可以在 /.vimrc 中配置幾個空格來代表一個tab，從而來布局python 函數(shù)的縮進。3.2.tab鍵還是空格python 里有一句叫“以用空格為榮，以用tab 鍵為恥”。但全用空格時確實很麻煩。因此，

5、這里不限定用tab 鍵還是空格。但記住：不可混用！你可以選擇全部使用tab 鍵，這樣也不會出錯。3.3.行的最大長度類似于函數(shù)中的行注釋、函數(shù)體等，如果某一行很長，則導致?lián)Q行折疊觀看，很影響美觀，而且還不利于閱讀。因此，對順序排放的的大塊文本（文檔字符串或注釋），推薦長度限制在 72 個字節(jié) 內(nèi)。推薦使用反斜杠續(xù)行。3.4.空行用兩行分割頂層函數(shù)和類的定義。用一行分割類成員方法的定義。在一個函數(shù)內(nèi)使用空行時請注意謹慎使用于一個邏輯段。3.5.編碼在 python 2.4 之后內(nèi)核已經(jīng)開始支持unicode 了。無論什么情況下，使用 utf-8才是王道 ！1 # -*- coding:utf-8

6、 -*-2 4. 導入通常應(yīng)該在單獨行中使用導入。例如：no: import sys, os yes: import sys import os 但是這樣也是可以的：from types import stringtype, listtype imports 應(yīng)該放在文件的頂部，僅在模塊注釋和文檔字符串之后，在模塊的全局變量和常量之前。imports 也是有順序的：1)python 標準庫的import ；2)第三方庫的import ；3)自定義的庫的import ；并且在每組的import 之間使用一行空行分割。5. 空格以下地方 不推薦 出現(xiàn)空格 : 1)緊挨著圓括號,方括號和花括號的如:

7、spam( ham 1 , eggs: 2 ).寫成 spam(ham1, eggs: 2) . 2)緊貼在逗號 ,分號或冒號前的如: if x = 4 : print x , y ; x , y = y , x. 寫成if x = 4: print x, y; x, y = y, x. 3)緊貼著函數(shù)調(diào)用的參數(shù)列表前開式括號的如: dict key = list index . 寫成dictkey = listindex . 4)緊貼在索引或切片下標開始的開式括號前如: dict key = list index. 寫成 dictkey = listindex . 5)在賦值 (或其它 )運

8、算符周圍的用于和其它并排的一個以上的空格,如: 1 x = 1 2 y = 2 3 long_variable = 3 寫成1 x = 1 2 y = 2 3 long_variable = 3 5.1.其它建議始終在這些二元運算符兩邊放置一個空格:賦值 (=), 比較 (=, , !=, , =, in, not in, is, is not), 布爾運算(and, or, not). 按你的看法在算術(shù)運算符周圍插入空格. 始終保持二元運算符兩邊空格的一致. 一些例子 : 1 i = i+1 2 submitted = submitted + 1 3 x = x*2 - 1 4 hypot2

9、 = x*x + y*y 5 c = (a+b) * (a-b) 6 c = (a + b) * (a - b) 不要在用于指定關(guān)鍵字參數(shù)或默認參數(shù)值的=號周圍使用空格,例如 : 1 def complex(real, imag=0.0): 2 return magic(r=real, i=imag) 不要將多條語句寫在同一行上. no: if foo = blah: do_blah_thing() yes: if foo = blah: do_blah_thing() no: do_one(); do_two(); do_three() yes: do_one() do_two() do_t

10、hree() 6. 注釋注釋必須跟代碼保持一致，當你想修改代碼時，建議優(yōu)先修改注釋。注釋必須是完整的句子。如果注釋是一個句子或者短語，請首字母大寫。如果注釋很短，建議省略句末的句號。注釋塊通常由一個或多個由完整句子構(gòu)成的段落組成，每個句子應(yīng)該以句號結(jié)尾。注釋請使用英文。約定使用統(tǒng)一的文檔化注釋格式有助于良好的習慣和團隊的進步。6.1注釋塊注釋塊通常應(yīng)用于跟隨著一些(或者全部 )代碼并和這些代碼有著相同的縮進層次。注釋塊中每行以#和一個空格開始(除非他是注釋內(nèi)的縮進文本)。注釋塊內(nèi)的段落以僅含單個#的行分割。注釋塊上下方最好有一空行包圍(或上方兩行下方一行，對一個新函數(shù)定義段的注釋)。6.2行內(nèi)

11、注釋行內(nèi)注釋應(yīng)該至少用兩個空格和語句分開. 它們應(yīng)該以 #和單個空格開始. x = x+1 # increment x 如果語意是很明了的,那么行內(nèi)注釋是不必要的,事實上是應(yīng)該被去掉的. 不要這樣寫 : x = x+1 # increment x x = x+1 # compensate for border 但是有時 ,這樣是有益的: x = x+1 # compensate for border 7. 文檔化為配合pydoc;epydoc,doxygen 等等文檔化工具的使用，應(yīng)該一直遵守編寫好的文檔字符串的約定。多行文檔字符串結(jié)尾的 應(yīng)該單獨成行，例如: return a foobang

12、 optional plotz says to frobnicate the bizbaz first. 對單行的文檔字符串,結(jié)尾的 在同一行也可以。8. 版本注解1 _version_ = $revision: 1.0.0.0 $ 這個行應(yīng)該包含在模塊的文檔字符串之后,所有代碼之前 ,上下用一個空行分割。當然也可以這樣：12version: 1.0.0.0 3跟其他相關(guān)信息（如author 、copyright 、date 等）一起。9. 命名約定現(xiàn)有的庫的命名約定想必比較混亂，但對于今后即將開發(fā)的新的模塊應(yīng)盡量遵循該約定開發(fā)。對于已有的模塊存在不同風格的，保證內(nèi)部的一致性是首選的。9.1.

13、描述：命名風格一般的命名風格大家都清楚。這里說幾個特殊的注意點：1） 單下劃線作為前導， 如：_single_begin， 這是弱的內(nèi)部使用標識，例如使用 “from m import *”的時候不會被導入；2） 單下劃線作為結(jié)尾的，如：single_end_，這一般用于跟python 關(guān)鍵詞沖突；3） 雙下劃線前導，如：_double_begin ，類私有名；4） 雙下劃線前導 +結(jié)尾，如： _double_begin_and_end_ ，特殊對象或?qū)傩裕嬖谟谟脩艨刂频拿臻g中，如：_init_，_import_ 等。有時可以被用戶定義，用于觸發(fā)某個特殊行為，如運算符重載。9.2. 說明

14、：命名約定9.2.1. 應(yīng)避免的名字永遠不要用：1） 小寫字母“ l” （小寫的“ l” ） ；2） 大寫字母“ o” ；3） 大寫字母“ i” （讀音 eye） ；作為單字符的變量名，因為不利于跟數(shù)字“0”和“ 1”很好的區(qū)分開來。當要用小寫字母“l(fā)”時，請用大寫字母“l(fā)”代替。9.2.2. 模塊名模塊應(yīng)該是不含下劃線的，簡短的，小寫的名字。因為模塊名被映射到文件名, 有些文件系統(tǒng)大小寫不敏感并且截短長名字, 模塊名被選為相當短是重要的-這在 unix 上不是問題 , 但當代碼傳到mac 或 windows 上就可能是個問題了。9.2.3. 類名幾乎沒有例外，類名總是使用首字母大寫、駝峰命名

15、單詞串的約定。9.2.4. 異常名首字母大寫、駝峰命名9.2.5. 全局變量名這個的約定跟用于函數(shù)的約定差不多。那些模塊，應(yīng)該在那些不想被導入的全局變量(還有內(nèi)部函數(shù)和類)前加一個下劃線)。9.2.6. 函數(shù)名函數(shù)名應(yīng)該為小寫、動賓短語，可能用 下劃線 風格單詞以增加可讀性。如：open_file() 9.2.7. 方法名和實例變量名小寫、動賓短語、下劃線風格以增加可讀性。單前導下劃線僅用于不打算作為類的公共接口的內(nèi)部方法。雙前導下劃線表示類私有的名字，python 將這些名字和類名連接在一起。如果類 foo 有一個屬性名為_a, 它不能以 foo._a 訪問，如果你非要訪問，還是可以通過 f

16、oo._foo_a得到訪問權(quán)。通常，雙前導下劃線應(yīng)該只用來避免與類中的屬性發(fā)生名字沖突。9.2.8. 繼承始終要確定一個類中的方法和實例變量是否要被公開。同樣， 確定你的屬性是否應(yīng)為私有的。私有與非公有的區(qū)別在于：前者永遠不會被用在一個派生類中，而后者可能會。私有屬性必須有兩個前導下劃線，無后置下劃線。非公有屬性必須有一個前導下劃線，無后置下劃線。公共屬性沒有前導和后置下劃線，除非它們與保留字沖突。10.設(shè)計建議1） 與像none 之類的單值進行比較的時候，應(yīng)永遠使用：is或 is not ：當你本意是 if x is not none 時，對寫成 if x 要小心，因為例如當你測試一個默認為

17、none的變量或參數(shù)是否被設(shè)置為其它值時，這個其它值可能是一個在布爾上下文中為假的值。2） 基于類的異常總是好過基于字符串的異常：模塊和包應(yīng)該定義它們自己的域內(nèi)特定的基異常類, 基類應(yīng)該是內(nèi)建的exception 類的子類。還始終包含一個類的文檔字符串。例如: 1 class messageerror(exception): 2 base class for errors in the email package. 3） 使用字符串方法代替字符串模塊：因為字符串方法總是非常的快。4） 在檢查前綴或后綴時避免對字符串進行切片：用 startswith() 和 endswith() 代替，因為它們

18、是明確的并且錯誤更少。例如：no: if foo:3 = bar: yes: if foo.startswith(bar): 5） 對象類型的比較應(yīng)該始終用isinstance() 代替直接比較類型：例如 : no: if type(obj) is type(1): yes: if isinstance(obj, int): 6） 檢查一個對象是否是字符串時,緊記它也可能是unicode字符串。7） 對序列 ,(字符串、 列表、 元組 )，使用空列表是false這個事實， 因此 if not seq或if seq比 if len(seq)或if not len(seq)好。8） 書寫字符串文字

19、時不要依賴于有意義的后置空格，這種后置空格在視覺上是不可辨別的。9） no chinese ！包括注釋，也請盡量使用英文。10）自動化 case中請使用python logging模塊設(shè)定日志級別打印日志，而不要大量使用 print 輸出。11）print時請使用 ” %d” 、” %s” 等標準輸出格式，請勿str和變量混合連接使用。11.demo 1#!/usr/bin/env python2# -*- coding:utf-8 -*-34_version_ = 1.0.0.05_author_ = cuijingjing6_date_ = thu nov 18 14:52:47 cst

20、20107_copyright_= baidu89import sys10import os11import shutil12import stat1314 -classopfile: 1516 -def _init_(self): 17pass1819 -def replace_file(self, file_name, replace_from, replace_to ): 2021note: replace some string in a file, link sed22parameter file_name: the file you want to deal with23param

21、eter replace_from: string you want to replace24parameter replace_to: the string you want to replace to2526if not os.path.exists(file_name): 27print file not exists.28exit() 2930file_name = os.path.abspath (file_name) 3132ori_file = open (file_name,r).read() 33if ori_file.find(replace_from) != -1: 34

22、if shutil.copyfile(file_name, file_name + .bak) != -1: # backup first35replace_in = open(file_name + .bak, r) 36replace_out = open(file_name, w) 37s = replace_in.read() 38replace_out .write(s.replace (replace_from, replace_to ) 39else : 40print error not find + replace_from + in + file_name + 41exit

23、() 4243if _name_ = _main_: 44op_file = opfile() 45op_file.replace_file(/home/cuijingjing/dgl/bin/test/test.c , cuijingjing , nnrand48) 46這里我寫的demo，也不一定完全百分百地跟規(guī)范一模一樣，但至少能確保他人閱讀起來不會費勁。用 epydoc 生成文檔后，epydoc 會識別出你的注釋信息，并在moudle 中體現(xiàn)出來，如下圖：對于類方法， 它的參數(shù) （parameters）是什么， 它是用來干什么的（ note）都一目了然。12.the zen of python 最后附上 the zen of python ，希望我們的開發(fā)越來越規(guī)范，整個團隊進步越來越快！the zen of pythonby tim peters beautiful is better than ugly. expli