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

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類名使用駝峰(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è)模塊.1.2類名函數(shù)名一律小寫(xiě)，如有多個(gè)單詞，用下劃線隔開(kāi) def run(): pass def run_with_env(): pass 私有函數(shù)在函數(shù)前加一個(gè)下劃線_ class Person(): def _private_func(): pass1.3函數(shù)編寫(xiě)函數(shù)的幾個(gè)原則函數(shù)設(shè)計(jì)要盡量短小，嵌套層次不宜過(guò)深；函數(shù)申明應(yīng)做到合理、簡(jiǎn)單、易于使用，函數(shù)名應(yīng)能正確反映函數(shù)大體功能，參數(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)的變量名；常量使用以下劃線分隔的大寫(xiě)命名 MAX_OVERFLOW = 100 Class FooBar: def foo_bar(self, print_): print(print_)變量名盡量小寫(xiě), 如有多個(gè)單詞，用下劃線隔開(kāi) if _name_ = _main_: count = 0 school_name = 常量采用全大寫(xiě)，如有多個(gè)單詞，使用下劃線隔開(kāi) MAX_CLIENT = 100 MAX_CONNECTION = 1000 CONNECTION_TIMEOUT = 6001.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.對(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_）第二章 簡(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)中的行隱式的連接起來(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” 文檔字符串 (docstring) 使用三個(gè)雙引號(hào) “”“”“”2.4空行模塊級(jí)函數(shù)和類定義之間空兩行； class A: def _init_(self): pass def hello(self): pass def main(): pass 可以使用多個(gè)空行分隔多組相關(guān)的函數(shù)函數(shù)中可以使用空行分隔出邏輯相關(guān)的代碼類成員函數(shù)之間空一行；正確的寫(xiě)法i = i + 1submitted += 1x = x * 2 - 1hypot2 = x * x + y * yc = (a + b) * (a - b)不推薦的寫(xiě)法i=i+1submitted +=1x = x*2 - 1hypot2 = x*x + y*yc = (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)之前不要多余的空格正確的寫(xiě)法dictkey = listindex不推薦的寫(xiě)法dict key = list index不要為對(duì)齊賦值語(yǔ)句而使用的額外空格正確的寫(xiě)法x = 1y = 2long_variable = 3 不推薦的寫(xiě)法x = 1y = 2long_variable = 32.5空格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.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)注釋和代碼至少要有兩個(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. 外部不可見(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ù)相同的格式.1.1、塊注釋“#”號(hào)后空一格，段落件用空行分開(kāi)（同樣需要“#”號(hào)）# 塊注釋# 塊注釋# 塊注釋# 塊注釋1.2、行注釋至少使用兩個(gè)空格和語(yǔ)句分開(kāi)，注意不要使用無(wú)意義的注釋# 正確的寫(xiě)法x = x + 1 # 邊框加粗一個(gè)像素3.6塊注釋和行注釋不推薦的注釋# 不推薦的寫(xiě)法(無(wú)意義的注釋)x = x + 1 # x加11.3、建議在代碼的關(guān)鍵部分(或比較復(fù)雜的地方), 能寫(xiě)注釋的要盡量寫(xiě)注釋比較重要的注釋段, 使用多個(gè)等號(hào)隔開(kāi), 可以更加醒目, 突出重要性app = create_app(name, options)# =# 請(qǐng)勿在此處添加 get post等app路由行為 !# =if _name_ = _main_: app.run()3.7 TODO注釋1.TODO注釋?xiě)?yīng)該在所有開(kāi)頭處包含”TODO”字符串, 緊跟著是用括號(hào)括起來(lái)的你的名字, email地址或其它標(biāo)識(shí)符. 然后是一個(gè)可選的冒號(hào). 接著必須有一行注釋, 解釋要做什么 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)入正確的寫(xiě)法import osimport sys不推薦的寫(xiě)法import sys,os正確的寫(xiě)法from subprocess import Popen, PIPEimport語(yǔ)句應(yīng)該使用 absolute import 正確的寫(xiě)法from foo.bar import Bar不推薦的寫(xiě)法from .bar import Barimport語(yǔ)句應(yīng)該放在文件頭部，置于模塊說(shuō)明及docstring之后，于全局變量之前；import語(yǔ)句應(yīng)該按照順序排列，每組之間用一個(gè)空行分隔import osimport sysimport msgpackimport zmqimport foo導(dǎo)入其他模塊的類定義時(shí)，可以使用相對(duì)導(dǎo)入from myclass import MyClass3. 每種分組中, 應(yīng)該根據(jù)每個(gè)模塊的完整包路徑按字典序排序, 忽略大小寫(xiě).如果發(fā)生命名沖突，則可使用命名空間import barimport foo.bar4.2二元運(yùn)算符換行(PEP8)# 推薦：運(yùn)算符和操作數(shù)很容易進(jìn)行匹配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.頂級(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，webDjango表示project每個(gè)業(yè)務(wù)模塊可以自建一個(gè)model和與之對(duì)應(yīng)的viewmodel目錄下主要處理數(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)題. 你的 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ì), 定義另外專門的區(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)航欄) 應(yīng)該