代碼規範

代碼規範

Python部分代碼規範

代碼格式

縮進

• 統一使用 4 個空格進行縮進

行寬

每行代碼儘可能不超過 80 個字符(在特殊狀況下能夠略微超過 80 ，但最長不得超過 120)理由：

• 這在查看 side-by-side 的 diff 時頗有幫助
• 方便在控制檯下查看代碼
• 太長多是設計有缺陷

引號

• 天然語言 使用雙引號 "..."
  例如錯誤信息；不少狀況仍是 unicode，使用u"你好世界"
• 機器標識 使用單引號 '...'
  例如 dict 裏的 key
• 正則表達式 使用原生的雙引號 r"..."
• 文檔字符串 (docstring) 使用三個雙引號 """......"""

空行

• 模塊級函數和類定義之間空兩行；
• 類成員函數之間空一行；
• 可使用多個空行分隔多組相關的函數
• 函數中可使用空行分隔出邏輯相關的代碼

空格

• 在二元運算符兩邊各空一格[=,-,+=,==,>,in,is not, and]:
• 函數的參數列表中，,以後要有空格
• 函數的參數列表中，默認值等號兩邊不要添加空格
• 左括號以後，右括號以前不要加多餘的空格
• 字典對象的左括號以前不要多餘的空格
• 不要爲對齊賦值語句而使用的額外空格

換行

Python 支持括號內的換行。這時有兩種狀況。

1. 第二行縮進到括號的起始處

2. 第二行縮進 4 個空格，適用於起始括號就換行的情形

命名規範

模塊

• 模塊儘可能使用小寫命名，首字母保持小寫，儘可能不要用下劃線(除非多個單詞，且數量很少的狀況

類名

• 類名使用駝峯(CamelCase)命名風格，首字母大寫，私有類可用一個下劃線開頭
• 將相關的類和頂級函數放在同一個模塊裏. 不像Java, 不必限制一個類一個模塊.

函數

• 函數名一概小寫，若有多個單詞，用下劃線隔開
• 私有函數在函數前加一個下劃線_

變量名

• 變量名儘可能小寫, 若有多個單詞，用下劃線隔開
• 常量採用全大寫，若有多個單詞，使用下劃線隔開

常量

• 常量使用如下劃線分隔的大寫命名

註釋

塊註釋

• 「#」號後空一格，段落件用空行分開（一樣須要「#」號）

行註釋

• 至少使用兩個空格和語句分開，注意不要使用無心義的註釋

文檔註釋

• 文檔註釋以 """ 開頭和結尾, 首行不換行, 若有多行, 末行必需換行, 如下是Google的docstring風格示例
• 不要在文檔註釋複製函數定義原型, 而是具體描述其具體內容, 解釋具體參數和返回值等
• 對函數參數、返回值等的說明採用numpy標準, 以下所示
• 文檔註釋不限於中英文, 但不要中英文混用
• 文檔註釋不是越長越好, 一般一兩句話能把狀況說清楚便可
• 模塊、公有類、公有方法, 能寫文檔註釋的, 應該儘可能寫文檔註釋

HTML部分代碼規範

• 使用正確的文檔類型，文檔類型聲明位於HTML文檔的第一行。
• 使用小寫元素名HTML5 元素名可使用大寫和小寫字母。本項目中均採用小寫字母。
• 關閉全部HTML元素，在本項目中全部元素均要添加關閉標籤。
• 使用小寫屬性名，在本項目中全部屬性名均事情小寫字母。
• 空格和等號，本項目中等號先後不添加空格。
• 空行和鎖縮進，不平白無故添加空行，比較短的代碼間不要使用沒必要要的空行和縮進。

JS部分代碼規範

• 命名規則，JS部分命名規則與Python部分命名規則相同。
• 空格與運算符，一般運算符 ( = + - * / ) 先後須要添加空格。
• 代碼縮進，一般使用 4 個空格符號來縮進代碼塊。
• 對象規則：將左花括號與類名放在同一行；冒號與屬性值間有個空格；字符串使用雙引號，數字不須要；最後一個屬性值後面不添加逗號；將右花括號獨立放在一行，並以分號做爲結束符號。
• 每行代碼字符建議小於80個，便於閱讀。