Jumpserver 項目規範（Draft）

語言框架

1. Python 3.6.1 (當前最新)
2. Django 1.11 (當前最新)
3. Flask 0.12 Luna (當前最新)
4. Paramiko 2.12 Coco (當前最新)

Django規範

1. 盡量使用Class Base View編程，更少代碼
2. 使用Django Form
3. 每個url獨立命名，不要硬編碼，同理static也是
4. 數據庫表名手動指定，不要使用默認
5. 代碼優雅簡潔
6. 註釋明確優美
7. 測試案例盡可能完整
8. 盡可能利用Django造好的輪子

代碼風格

Python方面大致的風格，我們采用pocoo的Style Guidance，但是有些細節部分會盡量放開 參考國內翻譯

基本的代碼布局

縮進

1. Python嚴格采用4個空格的縮進，任何python代碼都都必須遵守此規定。
2. 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‘

語句和表達式

一般空格規則

1. 單目運算符與運算對象之間不空格（例如，-，~等），即使單目運算符位於括號內部也一樣。
2. 雙目運算符與運算對象之間要空格。

exp = -1.05
value = (item_value / item_count) * offset / exp
value = my_list[index]
value = my_dict[‘key‘]

比較

1. 任意類型之間的比較，使用“==”和“!=”。
2. 與單例（singletons）進行比較時，使用is和is not。
3. 永遠不要與True或False進行比較（例如，不要這樣寫：foo == False，而應該這樣寫：not foo）。

否定成員關系檢查

使用foo not in bar，而不是not foo in bar。

命名約定

1. 類名稱：采用駱駝拼寫法（CamelCase），首字母縮略詞保持大寫不變（HTTPWriter，而不是HttpWriter）。
2. 變量名：小寫_以及_下劃線（lowercase_with_underscores）。
3. 方法與函數名：小寫_以及_下劃線（lowercase_with_underscores）。
4. 常量：大寫_以及_下劃線（UPPERCASE_WITH_UNDERSCORES）。
5. 預編譯的正則表達式：name_re。
6. 受保護的元素以一個下劃線為前綴。雙下劃線前綴只有定義混入類（mixin classes）時才使用。
7. 如果使用關鍵詞（keywords）作為類名稱，應在名稱後添加後置下劃線（trailing underscore）。 允許與內建變量重名，不要在變量名後添加下劃線進行區分。如果函數需要訪問重名的內建變量，請將內建變量重新綁定為其他名稱。
8. 命名要有寓意, 不使用拼音,不使用無意義簡單字母命名 (循環中計數例外 for i in)
9. 命名縮寫要謹慎, 盡量是大家認可的縮寫

函數和方法的參數：

1. 類方法：cls為第一個參數。
2. 實例方法：self為第一個參數。
3. 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代碼規範