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

Python開發(fā)規(guī)范總則概況：Python風(fēng)格規(guī)范 ，包含了部分Google風(fēng)格規(guī)范和PEP8規(guī)范。包括Django項目目錄結(jié)構(gòu)的一些規(guī)范，為適應(yīng)我們實際需求，提高開發(fā)中代碼更加可觀性、易讀性擬定的規(guī)范。第一章 命名規(guī)范1.1模塊模塊盡量使用小寫命名，首字母保持小寫，盡量不要用下劃線(除非多個單詞，且數(shù)量不多的情況)# 正確的模塊名 import decoder import html_parser # 不推薦的模塊名 import Decoder類名使用駝峰(CamelCase)命名風(fēng)格，首字母大寫，私有類可用一個下劃線開頭 class Farm(): pass class AnimalFarm(Farm): pass class _PrivateFarm(Farm): pass 將相關(guān)的類和頂級函數(shù)放在同一個模塊里. 不像Java, 沒必要限制一個類一個模塊.1.2類名函數(shù)名一律小寫，如有多個單詞，用下劃線隔開 def run(): pass def run_with_env(): pass 私有函數(shù)在函數(shù)前加一個下劃線_ class Person(): def _private_func(): pass1.3函數(shù)編寫函數(shù)的幾個原則函數(shù)設(shè)計要盡量短小，嵌套層次不宜過深；函數(shù)申明應(yīng)做到合理、簡單、易于使用，函數(shù)名應(yīng)能正確反映函數(shù)大體功能，參數(shù)設(shè)計應(yīng)簡潔明了，參數(shù)個數(shù)不宜過多；函數(shù)參數(shù)設(shè)計應(yīng)考慮向下兼容；一個函數(shù)只做一件事，盡量保證函數(shù)語句粒度的一致性；1.4變量名避免只用大小寫來區(qū)分不同的對象；避免使用容易引起混淆的名稱，變量名應(yīng)與所解決的問題域一致；不要害怕過長的變量名；常量使用以下劃線分隔的大寫命名 MAX_OVERFLOW = 100 Class FooBar: def foo_bar(self, print_): print(print_)變量名盡量小寫, 如有多個單詞，用下劃線隔開 if _name_ = _main_: count = 0 school_name = 常量采用全大寫，如有多個單詞，使用下劃線隔開 MAX_CLIENT = 100 MAX_CONNECTION = 1000 CONNECTION_TIMEOUT = 6001.5常量1.6其他規(guī)則1.所謂”內(nèi)部(Internal)”表示僅模塊內(nèi)可用, 或者, 在類內(nèi)是保護或私有的. 2.用單下劃線(_)開頭表示模塊變量或函數(shù)是protected的(使用import * from時不會包含). 3.用雙下劃線(_)開頭的實例變量或方法表示類內(nèi)私有. 4.將相關(guān)的類和頂級函數(shù)放在同一個模塊里. 不像Java, 沒必要限制一個類一個模塊. 5.對類名使用大寫字母開頭的單詞(如CapWords, 即Pascal風(fēng)格), 但是模塊名應(yīng)該用小寫加下劃線的方式(如lower_with_under.py).1.7應(yīng)該避免的名稱1.單字符名稱2.包/模塊名中使用連字符(-)而不使用下劃線(_)3.雙下劃線開頭并結(jié)尾的名稱（如_init_）第二章 簡明概述2.1編碼如無特殊情況, 文件一律使用 UTF-8 編碼 如無特殊情況, 文件頭部必須加入#-coding:utf-8-標識2.2代碼格式2.2.1、縮進 統(tǒng)一使用 4 個空格進行縮進 2.2.2、行寬 每行代碼盡量不超過 80 個字符(在特殊情況下可以略微超過 80 ，但最長不得超過 120) 2.2.3不要使用反斜杠連接行2.2.4 Python會將 圓括號, 中括號和花括號中的行隱式的連接起來 , 你可以利用這個特點. 如果需要, 你可以在表達式外圍增加一對額外的圓括號.2.2.5對于行連接的情況, 你應(yīng)該要么垂直對齊換行的元素, 或者使用4空格的懸掛式縮進(這時第一行不應(yīng)該有參數(shù)):理由： 這在查看 side-by-side 的 diff 時很有幫助 方便在控制臺下查看代碼 太長可能是設(shè)計有缺陷2.3引號簡單說，自然語言使用雙引號，機器標示使用單引號，因此 代碼里 多數(shù)應(yīng)該使用 單引號 自然語言 使用雙引號 “” 例如錯誤信息；很多情況還是 unicode，使用u”你好世界” 機器標識 使用單引號 例如 dict 里的 key 正則表達式 使用原生的雙引號 r” 文檔字符串 (docstring) 使用三個雙引號 “”“”“”2.4空行模塊級函數(shù)和類定義之間空兩行； class A: def _init_(self): pass def hello(self): pass def main(): pass 可以使用多個空行分隔多組相關(guān)的函數(shù)函數(shù)中可以使用空行分隔出邏輯相關(guān)的代碼類成員函數(shù)之間空一行；正確的寫法i = i + 1submitted += 1x = x * 2 - 1hypot2 = x * x + y * yc = (a + b) * (a - b)不推薦的寫法i=i+1submitted +=1x = x*2 - 1hypot2 = x*x + y*yc = (a+b) * (a-b)函數(shù)的參數(shù)列表中，,之后要有空格正確的寫法def complex(real, imag): pass 不推薦的寫法def complex(real,imag): pass函數(shù)的參數(shù)列表中，默認值等號兩邊不要添加空格 正確的寫法def complex(real, imag=0.0): pass 不推薦的寫法def complex(real, imag = 0.0): pass左括號之后，右括號之前不要加多余的空格 正確的寫法spam(ham1, eggs: 2)不推薦的寫法spam( ham1, eggs : 2 )字典對象的左括號之前不要多余的空格正確的寫法dictkey = listindex不推薦的寫法dict key = list index不要為對齊賦值語句而使用的額外空格正確的寫法x = 1y = 2long_variable = 3 不推薦的寫法x = 1y = 2long_variable = 32.5空格1. 括號內(nèi)不要有空格2. 不要在逗號，分號，冒號前面加空格，而應(yīng)該在它們的后面加3. 二元操作符兩邊都要加上一個空格（=， =，, !=, in, not .）4. 當=用于指示關(guān)鍵字參數(shù)或默認參數(shù)值時5. 不要用空格來垂直對齊多行間的標記, 因為這會成為維護的負擔(dān)(適用于:, #, =等)2.6換行第三章 注釋規(guī)范3.1文檔字符串Python使用文檔字符串作為注釋方式: 文檔字符串是包, 模塊, 類或函數(shù)里的第一個語句. 這些字符串可以通過對象的doc成員被自動提取, 并且被pydoc所用. 我們對文檔字符串的慣例是使用三重雙引號”“”( PEP-257 ). 一個文檔字符串應(yīng)該這樣組織: 1. 首先是一行以句號, 問號或驚嘆號結(jié)尾的概述(或者該文檔字符串單純只有一行). 接著是一個空行. 2. 接著是文檔字符串剩下的部分, 它應(yīng)該與文檔字符串的第一行的第一個引號對齊.3.2行內(nèi)注釋(PEP8)行內(nèi)注釋是與代碼語句同行的注釋 1. 行內(nèi)注釋和代碼至少要有兩個空格分隔 2. 注釋由#和一個空格開始，如下：x = x + 1 # Compensate for border3.3模塊注釋每個文件應(yīng)該最好包含一個許可樣板. 根據(jù)項目使用的許可(例如, 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ù)和方法一個函數(shù)必須要有文檔字符串, 除非它滿足以下條件: 1. 外部不可見 2. 非常短小 3. 簡單明了文檔字符串應(yīng)該包含函數(shù)做什么, 以及輸入和輸出的詳細描述 文檔字符串應(yīng)該提供足夠的信息, 當別人編寫代碼調(diào)用該函數(shù)時, 他不需要看一行代碼, 只要看文檔字符串就可以了 對于復(fù)雜的代碼, 在代碼旁邊加注釋會比使用文檔字符串更有意義.3.5類類應(yīng)該在其定義下有一個用于描述該類的文檔字符串. 如果你的類有公共屬性(Attributes), 那么文檔中應(yīng)該有一個屬性(Attributes)段. 并且應(yīng)該遵守和函數(shù)參數(shù)相同的格式.1.1、塊注釋“#”號后空一格，段落件用空行分開（同樣需要“#”號）# 塊注釋# 塊注釋# 塊注釋# 塊注釋1.2、行注釋至少使用兩個空格和語句分開，注意不要使用無意義的注釋# 正確的寫法x = x + 1 # 邊框加粗一個像素3.6塊注釋和行注釋不推薦的注釋# 不推薦的寫法(無意義的注釋)x = x + 1 # x加11.3、建議在代碼的關(guān)鍵部分(或比較復(fù)雜的地方), 能寫注釋的要盡量寫注釋比較重要的注釋段, 使用多個等號隔開, 可以更加醒目, 突出重要性app = create_app(name, options)# =# 請勿在此處添加 get post等app路由行為 !# =if _name_ = _main_: app.run()3.7 TODO注釋1.TODO注釋應(yīng)該在所有開頭處包含”TODO”字符串, 緊跟著是用括號括起來的你的名字, email地址或其它標識符. 然后是一個可選的冒號. 接著必須有一行注釋, 解釋要做什么 2.如果你的TODO是”將來做某事”的形式, 那么請確保你包含了一個指定的日期(“2009年11月解決”)或者一個特定的事件第四章 其他規(guī)范4.1模塊導(dǎo)入1. 每個導(dǎo)入應(yīng)該獨占一行2. 模塊導(dǎo)入順序1標注庫導(dǎo)入2第三方庫導(dǎo)入3應(yīng)用程序指定導(dǎo)入正確的寫法import osimport sys不推薦的寫法import sys,os正確的寫法from subprocess import Popen, PIPEimport語句應(yīng)該使用 absolute import 正確的寫法from foo.bar import Bar不推薦的寫法from .bar import Barimport語句應(yīng)該放在文件頭部，置于模塊說明及docstring之后，于全局變量之前；import語句應(yīng)該按照順序排列，每組之間用一個空行分隔import osimport sysimport msgpackimport zmqimport foo導(dǎo)入其他模塊的類定義時，可以使用相對導(dǎo)入from myclass import MyClass3. 每種分組中, 應(yīng)該根據(jù)每個模塊的完整包路徑按字典序排序, 忽略大小寫.如果發(fā)生命名沖突，則可使用命名空間import barimport foo.bar4.2二元運算符換行(PEP8)# 推薦：運算符和操作數(shù)很容易進行匹配income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest)4.3其它規(guī)范1.不要在行尾加分號, 也不要用分號將兩條命令放在同一行. 2.除非是用于實現(xiàn)行連接, 否則不要在返回語句或條件語句中使用括號. 不過在元組兩邊使用括號是可以的. 3.頂級定義之間空兩行, 方法定義之間空一行4.4Pandas使用規(guī)范1. pandas數(shù)據(jù)結(jié)構(gòu)命名 df_、se_2. df取一列，禁止使用df.列名，可以使用df列名, 建議使用df.loc:, 列名3. 禁止使用df.ix第五章 Django開發(fā)規(guī)范Django 采用的是MTV開發(fā)模式Model(模型)：數(shù)據(jù)庫相關(guān)的操作(ORM)Template(模版)：模板語法-將變量（數(shù)據(jù)庫數(shù)據(jù)）如何巧妙嵌入html頁面中View(視圖)：邏輯處理此外，Django還有一個urls分發(fā)器：路徑與視圖函數(shù)的映射關(guān)系5.1Django目錄結(jié)構(gòu)上圖zoneyet=app，webDjango表示project每個業(yè)務(wù)模塊可以自建一個model和與之對應(yīng)的viewmodel目錄下主要處理數(shù)據(jù)model下每個model對應(yīng)寫一個model的Manager業(yè)務(wù)邏輯方法一般原則上每個model對應(yīng)一個表，對應(yīng)一個Manager業(yè)務(wù)處理。view調(diào)用Manager方法實現(xiàn)，最終通過模板或者接口實現(xiàn)功能。5.2標準化Django模板（Template）區(qū)塊 (block) 名稱為了盡量標準化 Django 模板區(qū)塊 (block) 名稱, 我建議通常情況下使用以下區(qū)塊名稱.% block title %這個區(qū)塊用來定義頁面的標題. 你的 base.html 模板很可能要在這個 tag 之外定義 站點名字 (Sites name) (即便使用了 Sites 框架), 以便能夠放在所有頁面中.% block extra_head %我認為這是個非常有用的區(qū)塊, 很多人已經(jīng)以某種方式在使用了. 很多頁面經(jīng)常需要在 HTML 文檔頭添加些信息, 比如 RSS 源, Javascript, CSS, 以及別的應(yīng)該放在文檔頭的信息. 你可以, 也很可能將會, 定義另外專門的區(qū)塊 (比如前面的 title 區(qū)塊) 來添加文檔頭的其它部分的信息.% block body %這個 tag 用來包含頁面的整個 body 部分. 這使得你在 app 中創(chuàng)建的頁面 能夠替換整個頁面內(nèi)容, 不僅僅是正文內(nèi)容. 這種做法雖不常見, 但當你需要時, 它確實是一個非常方便的 tag. 你可能還沒注意到, 我一直盡可能的使 tag 名字和 HTML 標簽名稱保持一致.% block menu %你的菜單 (導(dǎo)航欄) 應(yīng)該