PEP8規範

PEP 8

Python 編碼規範：https://www.python.org/dev/peps/pep-0008/

• 1.Eclipse 中配置 PEP 8 代碼提示

將 PyDev 升級到高於 2.3.0 版本，打開 Window > Preferences > PyDev > Editor > Code

• 2.PyCharm 配置 PEP 8 代碼提示

直接在右下角調整 Highlighting Level 爲 Inspections 就能自動 PEP 8提示

 

• 3.建議修改在使用的 IDE 中修改 PEP8 的每行字數不超79字符規範，可修改成

Django 建議的 119 字符

說明：其餘編輯器或IDE配置請自行搜索

編碼規範

【必須】代碼編碼

• 1.國際慣例，文件編碼和 Python 編碼格式所有爲 utf-8 ，例如：在 Python 代碼的開頭，要統一加上 # -*- coding: utf-8 -*-。
• 2.Python 代碼中，非 ascii 字符的字符串，請需添加u前綴

 •

• 3.若出現 Python編 碼問題，可按照如下操做嘗試解決：

在 Python 的安裝路徑中下的 /Lib/site-packages 下面建立文件 sitecustomize.py，內容以下

•

若是沒有加入該文件，則在有編碼問題的 .py 代碼中，加入如下代碼：

 

Python編碼規範

【必須】命名規範

• 1.包名、模塊名、局部變量名、函數名全小寫+下劃線式駝峯

示例：this_is_var

• 2.全局變量

全大寫+下劃線式駝峯示例：GLOBAL_VAR

• 3.類名

首字母大寫式駝峯

示例：ClassName()

• 4.變量名命名

儘可能體現變量的數據類型和具體意義

注：

• • 變量名、類名取名必須有意義，嚴禁用單字母
  • 變量名不要用系統關鍵字，如 dir type str等等建議：
  • bool變量通常加上前綴 is_ 如：is_success

【必須】 import 順序

• • 標準庫
• • 第三方庫
• • 項目自己
• • (之間空行分隔)注：
• • 儘可能不要引用

【必•須】 models 內部定義順序

• 1.All database fields
• 2.Custom manager attributes
• 3.class Meta
• 4.def (str)
• 5.def save()
• 6.def get_absolute_url()
• 7.Any custom methods

異常捕獲處理原則

• 1.儘可能只包含容易出錯的位置，不要把整個函數 try catch
• 2.對於不會出現問題的代碼，就不要再用 try catch了
• 3.只捕獲有意義，能顯示處理的異常
• 4.能經過代碼邏輯處理的部分，就不要用 try catch
• 5.異常忽略，通常狀況下異常須要被捕獲並處理，但有些狀況下異常可被忽略，只須要用 log 記錄便可，可參考一下代碼：

 

return early原則

提早判斷並 return，減小代碼層級，加強代碼可讀性if not condition:

return

# a lot if code

 

Fat model， thin view

邏輯代碼和業務代碼解耦分離，功能性函數以及對數據庫的操做定義寫在 models 裏面， 業務邏輯寫在 view 裏面。

 

改成

 

權限校驗裝飾器異常拋出問題

建議權限不足時直接拋出異常，可使用 django 自帶的： from django.core.exceptions import PermissionDenied

權限不足時拋出異常 PermissionDenied，以後應該返回什麼樣的頁面由 handler 或者中間件去處理

分 method 獲取 request 參數問題

通常能夠分method 獲取request參數，這樣可以使代碼更可讀，且以後修改 method 時沒必要每一個參數都修改

args = request.GET if request.method == "GET" else request.POST business_name = args.get('business_name', '')

template_name = args.get('template_name', '')

使用數字、常量表示狀態

兩種的話改成 true/false，多種改成 enum 可讀性更好def enum(**enums):

return type("Enum", (), enums)

StatusEnum = enum( SUCCESS=True,

FAIL=False,

)

 

其餘注意問題

• 1.【必須】去除代碼中的 print，不然致使正式和測試環境 uwsgi 輸出大量信息
• 2.邏輯塊空行分隔
• 3.變量和其使用盡可能放到一塊兒
  • 4.【必須】 import過 長，要放在多行的時候，使用 from xxx import（a, b, c）,不要用 \ 換行
  • 5.Django Model 定義的 choices 直接在定義在類裏面
  • 6.【必須】參考藍鯨應用開發框架，把 Models 的初始化代碼放到 migrations 裏面

 

前端編碼規範

命名規則

類的基礎命名方式：「項目英文簡寫-當前頁-頁面內容塊」如 .ijobs-index-box。

Id 的基礎命名方式：語義化，並使用下滑槓鏈接，如步驟名稱可命名爲 #step_name

Javascript 變量命名方式：按照變量類型的首個字母爲前綴，使用駝峯命名法；

類型                         變量名 前綴

Array                        數組     a

Boolean                    布爾     b

Float                         浮點     l

Function                   函數     f

Integer(int)               整型     n

Object                       對象     o Regular Expression  正則         r

String                      字符串   s

例子：

var aName = ['zhangsan','lizi','zhaowu']; //Array 數 組

var oBtn = window.document.getElementById('btn'); //Object 對 象function fnName(){}; //Function 函 數

var nAge = 25; //Integer(int) 整 型

var sWebURL="www.wangyingran.com"; //String 字符串

日誌規範

【必須】日誌輸出級別

• Error：系統異常，影響用戶使用，必須通知到開發者及時修復。
• Warning：系統異常，不影響用戶使用，但有異常須要跟進修復。
• Info：系統流水日誌或平常記錄。不作通知配置
• 日誌須要包含當前函數名，方便查找和定位
• 重要操做流水直接記錄數據庫，能夠保存較長時間
• 錯誤日誌要方便定位問題，建議記錄當前參數以及上下文變量

日誌輸出格式

 

【必須】代碼提交規範

每次代碼提交必須有備註說明，註明本次提交作了哪些修改

commit 分類：

• 1.bugfix: ——– 線上功能 bug
• 2.sprintfix: —– 未上線代碼修改 （功能模塊未上線部分bug）
• 3.minor: ——— 不重要的修改（換行，拼寫錯誤等）
• 4.feature: —– 新功能說明

接口規範

【必須】Api 的 method

Api 的 method，要根據實際請求的類型，查詢必定要用 get，不能隨意指定 method。具體能夠參考文檔 《RESTful Web Services Cookbook-cn.pdf》 。

【必須】接口返回內容

接口返回內容開發建議直接參考藍鯨 apigateway 規範，返回的內容中包含 result code data message request_id 這幾個字段

字段名                                                 返回內容描述

result                                                    True/False

code                 現階段能夠不使用, 0表明正確，非0 表明不一樣的錯誤狀況；

data                                          成功時，返回的數據的內容

message                                    失敗時，返回的錯誤信息

request_id 標識 請求的id（能夠自動生成的惟一標識，方便追蹤請求記錄 uuid）

接口返回Status Code

建議充分利用 HTTP Status Code 做爲響應結果的基本狀態碼，基本狀態碼不能區分的status，再用響應 body 中」約定」的 code 進行補充

http狀態碼詳細說明請參考： https://zh.wikipedia.org/wiki/HTTP%E7%8A%B6%E6% 80%81%E7%A0%81

 

接口數據驗證

數據檢驗邏輯」應當」和業務邏輯分離，這樣作的好處：

• 1.代碼邏輯更加清晰
  • 2.數據校驗邏輯（可能）能夠複用分離方案：

1）form-data/url-params：Django-Form 2）Json：Json-schema

代碼註釋

【必須】Python 代碼註釋

• 1.方法必須使用標註註釋，若是是公有方法或對外提供的 API 相關方法，則最好給出使用樣例。如：

 

• 2.Module註釋：在開頭要加入對該模塊的註釋。如：

 

• 3.普通代碼註釋應該以‘#’和單個空格開始。
• 4.若是有須要調整或者須要優化的地方，可使用 #TODO 這裏是註釋內容」進行註釋，格式：'#'+單個空格+'TODO'+單個空格+註釋內容。
• 5.方法的返回，若是數據結構比較複雜，則必需要對返回結果的每一個屬性作解釋。

【必須】前端代碼註釋

Html 註釋

<!-- 容器 -->

<div class=「container」>

...

<!-- 用戶名 -->

<div id=「user_name」>

...

</div>

<!-- /用戶名 -->

...

</div>

<!-- /容器 -->

css 註釋

內容比較少是能夠只在頂部加註釋，內容比較多時在尾部加結束標籤/* 註釋內容 end */

/* 新建任務 start */

.new-task{}

/* 新建任務名 */

 

.task-name{color:#333;}

/* 新建任務時間 */

.task-created-time{background:url(img/clock.png) no-repeat;}

/* 新建任務 end */

Js 註釋

Js註釋同上，函數若是有參數，建議簡單備註一下參數的內容和類型。

Js 函數

更多規範請參考： http://magicbox.bk.tencent.com/#doc/show?id=html_structure

文件或包的引用

• 1.Python 代碼：模塊或包的引入最好使用完整路徑，即便是同一個包下的相互引用，也建議使用完整路徑。這樣比較方便代碼閱讀，同時若後續需修改成相對路徑也很簡單。
• 2.【必須】前端頁面：在頁面中引用 css 和 js、或配置 url 路徑時，必須使用「絕對路徑」，而不要使用‘../’，‘./’等相對路徑的引用方式