Python開(kāi)發(fā)規(guī)范

1、python 開(kāi)發(fā)規(guī)范總則概況： python 風(fēng)格規(guī)范，包含了部分google 風(fēng)格規(guī)范和 pep8規(guī)范。包括django 項(xiàng)目目錄結(jié)構(gòu)的一些規(guī)范，為適應(yīng)我們實(shí)際需求，提高開(kāi)發(fā)中代碼更加可觀性、易讀性擬定的規(guī)范。第一章命名規(guī)范1.1模塊模塊盡量使用小寫(xiě)命名，首字母保持小寫(xiě)，盡量不要用下劃線(除非多個(gè)單詞，且數(shù)量不多的情況 ) # 正確的模塊名import decoder import html_parser # 不推薦的模塊名import decoder 1.2類名1.3函數(shù)編寫(xiě)函數(shù)的幾個(gè)原則函數(shù)設(shè)計(jì)要盡量短小，嵌套層次不宜過(guò)深；函數(shù)申明應(yīng)做到合理、簡(jiǎn)單、易于使用，函數(shù)名應(yīng)能正確反映函數(shù)大體

2、功能，參數(shù)設(shè)計(jì)應(yīng)簡(jiǎn)潔明了，參數(shù)個(gè)數(shù)不宜過(guò)多；函數(shù)參數(shù)設(shè)計(jì)應(yīng)考慮向下兼容；一個(gè)函數(shù)只做一件事，盡量保證函數(shù)語(yǔ)句粒度的一致性；1.4變量名避免只用大小寫(xiě)來(lái)區(qū)分不同的對(duì)象；避免使用容易引起混淆的名稱，變量名應(yīng)與所解決的問(wèn)題域一致；不要害怕過(guò)長(zhǎng)的變量名；類名使用駝峰(camelcase)命名風(fēng)格，首字母大寫(xiě)，私有類可用一個(gè)下劃線開(kāi)頭class farm(): pass class animalfarm(farm): pass class _privatefarm(farm): pass 將相關(guān)的類和頂級(jí)函數(shù)放在同一個(gè)模塊里. 不像 java, 沒(méi)必要限制一個(gè)類一個(gè)模塊. 函數(shù)名一律小寫(xiě)，如有多個(gè)單詞，

3、用下劃線隔開(kāi)def run(): pass def run_with_env(): pass 私有函數(shù)在函數(shù)前加一個(gè)下劃線_ class person(): def _private_func(): pass 1.5常量1.6其他規(guī)則1.所謂”內(nèi)部 (internal)”表示僅模塊內(nèi)可用 , 或者, 在類內(nèi)是保護(hù)或私有的 . 2.用單下劃線 (_)開(kāi)頭表示模塊變量或函數(shù)是protected 的(使用 import * from時(shí)不會(huì)包含 ). 3.用雙下劃線 (_)開(kāi)頭的實(shí)例變量或方法表示類內(nèi)私有. 4.將相關(guān)的類和頂級(jí)函數(shù)放在同一個(gè)模塊里. 不像 java, 沒(méi)必要限制一個(gè)類一個(gè)模塊 . 5

4、.對(duì)類名使用大寫(xiě)字母開(kāi)頭的單詞(如 capwords, 即 pascal風(fēng)格), 但是模塊名應(yīng)該用小寫(xiě)加下劃線的方式(如 lower_with_under.py). 1.7應(yīng)該避免的名稱1.單字符名稱2.包/模塊名中使用連字符 (-)而不使用下劃線 (_) 3.雙下劃線開(kāi)頭并結(jié)尾的名稱（如_init_）變量名盡量小寫(xiě), 如有多個(gè)單詞，用下劃線隔開(kāi)if _name_ = _main_: count = 0 school_name = 常量采用全大寫(xiě)，如有多個(gè)單詞，使用下劃線隔開(kāi)max_client = 100 max_connection = 1000 connection_timeout =

5、600 常量使用以下劃線分隔的大寫(xiě)命名max_overflow = 100 class foobar: def foo_bar(self, print_): print(print_) 第二章簡(jiǎn)明概述2.1編碼如無(wú)特殊情況 , 文件一律使用utf-8 編碼如無(wú)特殊情況 , 文件頭部必須加入 #-coding:utf-8-標(biāo)識(shí)2.2代碼格式2.2.1、縮進(jìn) 統(tǒng)一使用4 個(gè)空格進(jìn)行縮進(jìn)2.2.2、行寬 每行代碼盡量不超過(guò)80 個(gè)字符 (在特殊情況下可以略微超過(guò)80 ，但最長(zhǎng)不得超過(guò)120) 2.2.3 不要使用反斜杠連接行2.2.4 python 會(huì)將 圓括號(hào) , 中括號(hào)和花括號(hào)中的行隱式的連接起

6、來(lái), 你可以利用這個(gè)特點(diǎn) . 如果需要 , 你可以在表達(dá)式外圍增加一對(duì)額外的圓括號(hào). 2.2.5 對(duì)于行連接的情況 , 你應(yīng)該要么垂直對(duì)齊換行的元素, 或者使用 4 空格的懸掛式縮進(jìn) (這時(shí)第一行不應(yīng)該有參數(shù)): 理由：這在查看side-by-side 的 diff 時(shí)很有幫助方便在控制臺(tái)下查看代碼太長(zhǎng)可能是設(shè)計(jì)有缺陷2.3引號(hào)簡(jiǎn)單說(shuō)，自然語(yǔ)言使用雙引號(hào)， 機(jī)器標(biāo)示使用單引號(hào)， 因此 代碼里 多數(shù)應(yīng)該使用 單引號(hào) 自然語(yǔ)言使用雙引號(hào)“”例如錯(cuò)誤信息；很多情況還是unicode，使用 u”你好世界”機(jī)器標(biāo)識(shí)使用單引號(hào)例如 dict 里的 key 正則表達(dá)式使用原生的雙引號(hào)r”文檔字符串(docs

7、tring) 使用三個(gè)雙引號(hào)“” “” “”2.4空行模塊級(jí)函數(shù)和類定義之間空兩行；類成員函數(shù)之間空一行；class a: def _init_(self): pass def hello(self): pass def main(): pass 可以使用多個(gè)空行分隔多組相關(guān)的函數(shù)函數(shù)中可以使用空行分隔出邏輯相關(guān)的代碼2.5空格正確的寫(xiě)法i = i + 1 submitted += 1 x = x * 2 - 1 hypot2 = x * x + y * y c = (a + b) * (a - b) 不推薦的寫(xiě)法i=i+1 submitted +=1 x = x*2 - 1 hypot2 =

8、 x*x + y*y c = (a+b) * (a-b) 函數(shù)的參數(shù)列表中，,之后要有空格正確的寫(xiě)法def complex(real, imag): pass 不推薦的寫(xiě)法def complex(real,imag): pass 函數(shù)的參數(shù)列表中，默認(rèn)值等號(hào)兩邊不要添加空格正確的寫(xiě)法def complex(real, imag=0.0): pass 不推薦的寫(xiě)法def complex(real, imag = 0.0): pass 左括號(hào)之后，右括號(hào)之前不要加多余的空格正確的寫(xiě)法spam(ham1, eggs: 2) 不推薦的寫(xiě)法spam( ham1, eggs : 2 ) 字典對(duì)象的左括號(hào)之

9、前不要多余的空格正確的寫(xiě)法dictkey = listindex 不推薦的寫(xiě)法dict key = list index 不要為對(duì)齊賦值語(yǔ)句而使用的額外空格正確的寫(xiě)法x = 1 y = 2 long_variable = 3 不推薦的寫(xiě)法x = 1 y = 2 long_variable = 3 1. 括號(hào)內(nèi)不要有空格2. 不要在逗號(hào)，分號(hào)，冒號(hào)前面加空格，而應(yīng)該在它們的后面加3. 二元操作符兩邊都要加上一個(gè)空格（=， =，, !=, in, not . ）4. 當(dāng)=用于指示關(guān)鍵字參數(shù)或默認(rèn)參數(shù)值時(shí)5. 不要用空格來(lái)垂直對(duì)齊多行間的標(biāo)記, 因?yàn)檫@會(huì)成為維護(hù)的負(fù)擔(dān)(適用于 :, #, =等) 2

10、.6 換行第三章注釋規(guī)范3.1文檔字符串python 使用文檔字符串作為注釋方式: 文檔字符串是包 , 模塊, 類或函數(shù)里的第一個(gè)語(yǔ)句 . 這些字符串可以通過(guò)對(duì)象的doc 成員被自動(dòng)提取 , 并且被 pydoc所用. 我們對(duì)文檔字符串的慣例是使用三重雙引號(hào)”“”( pep-257 ). 一個(gè)文檔字符串應(yīng)該這樣組織: 1. 首先是一行以句號(hào) , 問(wèn)號(hào)或驚嘆號(hào)結(jié)尾的概述(或者該文檔字符串單純只有一行 ). 接著是一個(gè)空行 . 2. 接著是文檔字符串剩下的部分, 它應(yīng)該與文檔字符串的第一行的第一個(gè)引號(hào)對(duì)齊 . 3.2行內(nèi)注釋 (pep8) 行內(nèi)注釋是與代碼語(yǔ)句同行的注釋1. 行內(nèi)注釋和代碼至少要有兩

11、個(gè)空格分隔2. 注釋由#和一個(gè)空格開(kāi)始，如下：x = x + 1 # compensate for border3.3模塊注釋每個(gè)文件應(yīng)該最好包含一個(gè)許可樣板. 根據(jù)項(xiàng)目使用的許可 (例如, apache 2.0, bsd, lgpl, gpl), 選擇合適的樣板 . # -*- coding: utf-8 -*-# (c) zoneyet, inc. 2018-2019# all rights reserved# licensed under simplified bsd license (see license)3.4函數(shù)和方法一個(gè)函數(shù)必須要有文檔字符串, 除非它滿足以下條件 : 1. 外

12、部不可見(jiàn)2. 非常短小3. 簡(jiǎn)單明了文檔字符串應(yīng)該包含函數(shù)做什么, 以及輸入和輸出的詳細(xì)描述文檔字符串應(yīng)該提供足夠的信息, 當(dāng)別人編寫(xiě)代碼調(diào)用該函數(shù)時(shí), 他不需要看一行代碼 , 只要看文檔字符串就可以了對(duì)于復(fù)雜的代碼 , 在代碼旁邊加注釋會(huì)比使用文檔字符串更有意義. 3.5類類應(yīng)該在其定義下有一個(gè)用于描述該類的文檔字符串. 如果你的類有公共屬性 (attributes), 那么文檔中應(yīng)該有一個(gè)屬性(attributes)段. 并且應(yīng)該遵守和函數(shù)參數(shù)相同的格式 . 3.6塊注釋和行注釋不推薦的注釋3.7 todo 注釋1.todo 注釋?xiě)?yīng)該在所有開(kāi)頭處包含”todo”字符串 , 緊跟著是用括號(hào)括

13、起來(lái)的你的名字 , email 地址或其它標(biāo)識(shí)符 . 然后是一個(gè)可選的冒號(hào) . 接著必須有一行注釋 , 解釋要做什么1.1、塊注釋“ #”號(hào)后空一格，段落件用空行分開(kāi)（同樣需要“#”號(hào)）# 塊注釋# 塊注釋# # 塊注釋# 塊注釋1.2、行注釋至少使用兩個(gè)空格和語(yǔ)句分開(kāi)，注意不要使用無(wú)意義的注釋# 正確的寫(xiě)法x = x + 1 # 邊框加粗一個(gè)像素# 不推薦的寫(xiě)法(無(wú)意義的注釋 ) x = x + 1 # x加 1 1.3、建議在代碼的關(guān)鍵部分(或比較復(fù)雜的地方), 能寫(xiě)注釋的要盡量寫(xiě)注釋比較重要的注釋段, 使用多個(gè)等號(hào)隔開(kāi), 可以更加醒目, 突出重要性app = create_app(nam

14、e, options) # = # 請(qǐng)勿在此處添加get post 等 app 路由行為! # = if _name_ = _main_: app.run() 2.如果你的 todo 是”將來(lái)做某事”的形式, 那么請(qǐng)確保你包含了一個(gè)指定的日期 (“2009 年 11 月解決” )或者一個(gè)特定的事件第四章其他規(guī)范4.1 模塊導(dǎo)入1. 每個(gè)導(dǎo)入應(yīng)該獨(dú)占一行2. 模塊導(dǎo)入順序1 標(biāo)注庫(kù)導(dǎo)入2 第三方庫(kù)導(dǎo)入3 應(yīng)用程序指定導(dǎo)入3. 每種分組中 , 應(yīng)該根據(jù)每個(gè)模塊的完整包路徑按字典序排序, 忽略大小寫(xiě) . 4.2 二元運(yùn)算符換行 (pep8) # 推薦：運(yùn)算符和操作數(shù)很容易進(jìn)行匹配正確的寫(xiě)法impor

15、t os import sys 不推薦的寫(xiě)法import sys,os 正確的寫(xiě)法from subprocess import popen, pipe import 語(yǔ)句應(yīng)該使用absolute import 正確的寫(xiě)法from foo.bar import bar 不推薦的寫(xiě)法from .bar import bar import 語(yǔ)句應(yīng)該放在文件頭部，置于模塊說(shuō)明及docstring 之后，于全局變量之前；import 語(yǔ)句應(yīng)該按照順序排列，每組之間用一個(gè)空行分隔import os import sys import msgpack import zmq import foo 導(dǎo)入其他模塊

16、的類定義時(shí)，可以使用相對(duì)導(dǎo)入from myclass import myclass 如果發(fā)生命名沖突，則可使用命名空間import bar import foo.bar income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest) 4.3 其它規(guī)范1. 不要在行尾加分號(hào) , 也不要用分號(hào)將兩條命令放在同一行. 2. 除非是用于實(shí)現(xiàn)行連接 , 否則不要在返回語(yǔ)句或條件語(yǔ)句中使用括號(hào). 不過(guò)在元組兩邊使用括號(hào)是可以的. 3.

17、頂級(jí)定義之間空兩行 , 方法定義之間空一行4.4pandas 使用規(guī)范1. pandas 數(shù)據(jù)結(jié)構(gòu)命名df_、se_ 2. df 取一列，禁止使用 df. 列名，可以使用 df列名 , 建議使用 df.loc:, 列名3. 禁止使用 df.ix第五章django開(kāi)發(fā)規(guī)范django 采用的是 mtv開(kāi)發(fā)模式model(模型)：數(shù)據(jù)庫(kù)相關(guān)的操作 (orm) template(模版)：模板語(yǔ)法 -將變量（數(shù)據(jù)庫(kù)數(shù)據(jù)）如何巧妙嵌入html 頁(yè)面中view(視圖)：邏輯處理此外， django還有一個(gè) urls 分發(fā)器：路徑與視圖函數(shù)的映射關(guān)系5.1django目錄結(jié)構(gòu)上圖 zoneyet=app，w

18、ebdjango 表示 project 每個(gè)業(yè)務(wù)模塊可以自建一個(gè)model 和與之對(duì)應(yīng)的 view model 目錄下主要處理數(shù)據(jù)model 下每個(gè) model 對(duì)應(yīng)寫(xiě)一個(gè) model 的 manager 業(yè)務(wù)邏輯方法一般原則上每個(gè) model 對(duì)應(yīng)一個(gè)表，對(duì)應(yīng)一個(gè)manager 業(yè)務(wù)處理。view 調(diào)用 manager 方法實(shí)現(xiàn)，最終通過(guò)模板或者接口實(shí)現(xiàn)功能。5.2標(biāo)準(zhǔn)化 django模板（ template ）區(qū)塊 (block) 名稱為了盡量標(biāo)準(zhǔn)化django 模板區(qū)塊(block) 名稱, 我建議通常情況下使用以下區(qū)塊名稱 . % block title % 這個(gè)區(qū)塊用來(lái)定義頁(yè)面的標(biāo)題

19、. 你的 base.html 模板很可能要在這個(gè)tag 之外定義 站點(diǎn)名字(sites name) (即便使用了sites 框架 ), 以便能夠放在所有頁(yè)面中. % block extra_head % 我認(rèn)為這是個(gè)非常有用的區(qū)塊, 很多人已經(jīng)以某種方式在使用了. 很多頁(yè)面經(jīng)常需要在 html 文檔頭添加些信息 , 比如 rss 源, javascript, css, 以及別的應(yīng)該放在文檔頭的信息 . 你可以 , 也很可能將會(huì) , 定義另外專門(mén)的區(qū)塊(比如前面的title 區(qū)塊) 來(lái)添加文檔頭的其它部分的信息. % block body % 這個(gè) tag 用來(lái)包含頁(yè)面的整個(gè)body 部分. 這使得你在app 中創(chuàng)建的頁(yè)面能夠替換整個(gè)頁(yè)面內(nèi)容, 不僅僅是正文內(nèi)容. 這種做法雖不常見(jiàn), 但當(dāng)你需要時(shí) , 它確實(shí)是一個(gè)非常方便的tag. 你可能還沒(méi)注意到 , 我一直盡可能的使tag 名字和 html 標(biāo)簽名稱保持一致 . % block menu % 你的菜單(導(dǎo)航