Jumpserver代碼規範
Jumpserver 項目規範(Draft)
語言框架
- Python 3.6.1 (當前最新)
- Django 1.11 (當前最新)
- Flask 0.12 Luna (當前最新)
- Paramiko 2.12 Coco (當前最新)
Django規範
- 盡量使用Class Base View編程,更少代碼
- 使用Django Form
- 每個url獨立命名,不要硬編碼,同理static也是
- 數據庫表名手動指定,不要使用默認
- 代碼優雅簡潔
- 註釋明確優美
- 測試案例盡可能完整
- 盡可能利用Django造好的輪子
代碼風格
Python方面大致的風格,我們采用pocoo的Style Guidance,但是有些細節部分會盡量放開 參考國內翻譯
基本的代碼布局
縮進
- Python嚴格采用4個空格的縮進,任何python代碼都都必須遵守此規定。
- web部分代碼(HTML, CSS, JavaScript),Node.js采用2空格縮進,同樣不使用tab (\t)。 之所以與Python不同,是因為js中有大量回調式的寫法,2空格可以顯著降低視覺上的負擔。
最大行長度
按PEP8規範,Python一般限制最大79個字符, 但是Django的命名,url等通常比較長, 而且21世紀都是寬屏了,所以我們限制最大120字符
補充說明:HTML代碼不受此規範約束。
長語句縮進
編寫長語句時,可以使用換行符(\)換行。在這種情況下,下一行應該與上一行的最後 一個“.”句點或“=”對齊,或者是縮進4個空格符
this_is_a_very_long(function_call, ‘with many parameters‘) .that_returns_an_object_with_an_attribute
MyModel.query.filter(MyModel.scalar > 120) .order_by(MyModel.name.desc()) .limit(10)
如果你使用括號“()”或花括號“{}”為長語句換行,那麽下一行應與括號或花括號對齊:
this_is_a_very_long(function_call, ‘with many parameters‘, 23, 42, ‘and even more‘)
對於元素眾多的列表或元組,在第一個“[”或“(”之後馬上換行:
items = [
‘this is the first‘, ‘set of items‘, ‘with more items‘,
‘to come in this line‘, ‘like this‘
]
空行
頂層函數與類之間空兩行,此外都只空一行。不要在代碼中使用太多的空行來區分不同的邏輯模塊。
def hello(name):
print ‘Hello %s!‘ % name
def goodbye(name):
print ‘See you %s.‘ % name
class MyClass(object):
"""This is a simple docstring."""
def __init__(self, name):
self.name = name
def get_annoying_name(self):
return self.name.upper() + ‘!!!!111‘
語句和表達式
一般空格規則
- 單目運算符與運算對象之間不空格(例如,-,~等),即使單目運算符位於括號內部也一樣。
- 雙目運算符與運算對象之間要空格。
exp = -1.05
value = (item_value / item_count) * offset / exp
value = my_list[index]
value = my_dict[‘key‘]
比較
- 任意類型之間的比較,使用“==”和“!=”。
- 與單例(singletons)進行比較時,使用is和is not。
- 永遠不要與True或False進行比較(例如,不要這樣寫:foo == False,而應該這樣寫:not foo)。
否定成員關系檢查
使用foo not in bar,而不是not foo in bar。
命名約定
- 類名稱:采用駱駝拼寫法(CamelCase),首字母縮略詞保持大寫不變(HTTPWriter,而不是HttpWriter)。
- 變量名:小寫_以及_下劃線(lowercase_with_underscores)。
- 方法與函數名:小寫_以及_下劃線(lowercase_with_underscores)。
- 常量:大寫_以及_下劃線(UPPERCASE_WITH_UNDERSCORES)。
- 預編譯的正則表達式:name_re。
- 受保護的元素以一個下劃線為前綴。雙下劃線前綴只有定義混入類(mixin classes)時才使用。
- 如果使用關鍵詞(keywords)作為類名稱,應在名稱後添加後置下劃線(trailing underscore)。 允許與內建變量重名,不要在變量名後添加下劃線進行區分。如果函數需要訪問重名的內建變量,請將內建變量重新綁定為其他名稱。
- 命名要有寓意, 不使用拼音,不使用無意義簡單字母命名 (循環中計數例外 for i in)
- 命名縮寫要謹慎, 盡量是大家認可的縮寫
函數和方法的參數:
- 類方法:cls為第一個參數。
- 實例方法:self為第一個參數。
- property函數中使用匿名函數(lambdas)時,匿名函數的第一個參數可以用x替代, 例如:display_name = property(lambda x: x.real_name or x.username)。
文檔註釋(Docstring,即各方法,類的說明文檔註釋)
所有文檔字符串均以reStructuredText格式編寫,方便Sphinx處理。文檔字符串的行數不同,布局也不一樣。 如果只有一行,代表字符串結束的三個引號與代表字符串開始的三個引號在同一行。 如果為多行,文檔字符串中的文本緊接著代表字符串開始的三個引號編寫,代表字符串結束的三個引號則自己獨立成一行。 (有能力盡可能用英文, 否則請中文優雅註釋)
def foo():
"""This is a simple docstring."""
def bar():
"""This is a longer docstring with so much information in there
that it spans three lines. In this case, the closing triple quote
is on its own line.
"""
文檔字符串應分成簡短摘要(盡量一行)和詳細介紹。如果必要的話,摘要與詳細介紹之間空一行。
模塊頭部
模塊文件的頭部包含有utf-8編碼聲明(如果模塊中使用了非ASCII編碼的字符,建議進行聲明),以及標準的文檔字符串。
# -*- coding: utf-8 -*-
"""
package.module
~~~~~~~~~~~~~~
A brief description goes here.
:copyright: (c) YEAR by AUTHOR.
:license: LICENSE_NAME, see LICENSE_FILE for more details.
"""
註釋(comment)
註釋的規範與文檔字符串編寫規範類似。二者均以reStructuredText格式編寫。 如果使用註釋來編寫類屬性的文檔,請在#符號後添加一個冒號":"。 (有能力盡可能用英文, 否則請中文優雅註釋)
class User(object):
#: the name of the user as unicode string
name = Column(String)
#: the sha1 hash of the password + inline salt
pw_hash = Column(String)
Jumpserver代碼規範