web开发规则,代码规范

精神

  • 絕對不寫死程式
  • 不留不要用的、垃圾程式碼

Git

  • Master 的 BUG 必須最少且趨近於零,为最稳定的版本
  • 每次 Commit 訊息應該確實填寫。不可模稜兩可,eg: 修复BUG、增加功能
  • 禁止 Commit IDE 的 project data
  • 禁止上傳垃圾程式碼
  • Gitea編輯內容類似里程碑和版本描述時要使用Markdown格式

分支(Branch)

  • 命名規則:應以此分支主要目的命名(修復什麼BUG,新增特定功能)
    不可出現版本號,模組ID
  • 合併後的分支應刪除

commit

  • 遵循一個功能一個commit的原則

Restful

  • 資源名詞站在API的角度思考
    • 複數名詞:可以複數筆資料,回傳結果為Array
      舉例:GET/users 取得多筆使用者資料
      • 刪除,放在複數名詞內,讓Router保持一致性
      • 增加,放在複數名詞內,讓Router保持一致性
    • 單數名詞:僅取得單筆資料,必須指定PK,兩兩一組,回傳結果為Object
      舉例:GET/user/{accont} 取得單筆使用者資料,必須指定PK
  • URL中一律不帶id參數
    1
    2
    正確範例: calendar_manager/calendar/29
    錯誤範例: calendar_manager/calendar/29?id=29

命名

  • 命名應根據內容做有意義的命名,讓後續維護人員可以顧名思義!
  • 即使不會發生錯誤,程式碼英文大小寫也需明確區分。

語意

類型命名規則說明
屬性 (Attribute, Property)名詞
user_name、userName
方法 (Method, Function)動詞+名詞
getUserName、get_user_name
常見的動詞有:get、set、update、delete、remove

字母與分隔

語言變數 (Variable, Parameter, Argument)常數 (Constant)物件導向 - 類名 (Class Name)物件導向 - 成員 (mebmer)
HTML、CSS全部小寫,不同單字以「-」分隔
user-id
JavaScript
駝峰式命名法
首字小寫,不同單字「首字以大寫」分隔
userId
全部大寫,不同單字以「_」分隔
MAX_COUNT
駝峰式命名法
首字大寫,不同單字「首字以大寫」分隔
一個檔案放一個 Class
檔名即為 Class Name
User
駝峰式命名法
公有 (public) : 首字小寫,不同單字「首字以大寫」分隔
name, getName
私有 (private): _公有命名規則
_name, getName
PHP全部小寫,不同單字以「」分隔
user_id
SQL由使用者定義的:表名、欄位名
全部小寫,不同單字以「_」分隔
SQL語法、函數
全部大寫
SELECT、INSERT INTO
-

通用

  • 程式碼撰寫
  • 每個函數應該註解,註解應包含函數工能說明、引數說明。
  • 不必要的代碼不要寫,也禁止放到註解裡面!
  • if-else 的 {} 嚴禁省略。
  • {} 起始一律跟在 前一個功能的尾巴,禁止分行

正確寫法

1
2
3
4
5
6
public function test(){
//do something
if($a === $b){
//do something
}
}

錯誤寫法

1
2
3
4
5
6
7
8
public function test()
{
//do something
if($a === $b)
{
//do something
}
}
  • 程式碼排版
    • 任何程式碼應該以 2 個 space 為一個階層做好排版、不可使用 tab。
  • 函數 (Function, Methd)
    • 函數宣告時需在函數上方加上函數註解,註解應包含函數說明、引數內容 (引數型態、引數英文名稱、引數說明)、 回傳值內容 (回傳值型態、回傳值說明)
  • 類 (Class)
    • 一個類 (Class) 的宣告只能存在一個檔案。
    • 類 (Class) 的宣告檔,檔名必須為類名。
  • 其他
    • 連結本地任何其他資源 (圖片、檔案、網站) 皆使用相對路徑,禁止使用絕對路徑,非本地資源除外。

HTML

程式碼撰寫

  • 禁止在 HTML 使用 <style><script>,一律使用外部檔案引用方式引用 CSS、JavaScript檔案。
  • HTML 標籤需成雙成對,有頭有尾。
  • 區塊標籤:<tag></tag>
  • 單標籤:<tag />
  • 禁止使用已被 HTML 捨棄的舊標籤、屬性,如:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<!-- html tag -->
<center>
<font>
<basefont>
<s>
<strike>
<u>
<listing>
<plaintext>
<xmp>
<!-- html attribute -->
align
bgcolor
color

資安禁止:

禁止使用 readonly 做為參數傳遞

其他

連結本地任何其他資源 (圖片、檔案、網站) 皆使用相對路徑,禁止使用絕對路徑,非本地資源除外。

CSS

程式碼撰寫

CSS 的定義應該獨立一個 CSS 檔案,禁止使用 <style>style 屬性直接在 HTML 中定義樣式。

JavaScript

程式碼撰寫

  • 禁止使用 HTML 字串,一律使用 Dom 產生 HTML
  • 禁止省略箭頭函數 (Arrow function) 的括弧

正確

1
2
3
a = (a, b) => {
c;
}

錯誤 (這是允許的,但造成程式碼閱讀困難,故禁止)

1
a  => c;

註解

JavaScript 註解應該遵循 JSDoc 的標準撰寫

全域變數 (Global)

1
/* global $t, Tiger */

常數 (Constant)

1
2
3
4
/**
* 常數說明
* @type {常數型態}
*/

Example

1
2
3
4
5
/**
* 使用者ID
* @type {String}
*/
var userId = 'Hello';

函數、方法 (Function, Method)

1
2
3
4
5
6
7
/**
* 函數用途說明
* @param {引數型態} 引數名稱 引數說明
* @param {引數型態} [選擇性引數名稱] 引數說明
* @param {引數型態} [選擇性引數名稱=引數預設值] 引數說明
* @returns {回傳值型態} 回傳值說明
*/

Example

1
2
3
4
5
6
7
8
9
10
11
/**
* 取得使用者
* @param {Int} userId 使用者ID
* @param {Object} [options] 其他選項
* @param {String} [options.query='a'] 查詢關鍵字 預設為 a
* @returns {Object} 使用者資料
*/
var getUser = function(userId, options){
//do something
return user;
};

PHP

前端參數取得

參數取得需透過 filter_input 函數取得,不得使用 $_GET、 $_POST

輸出到前台

參數命名必須為:全部小寫,不同單字以「_」分隔

註解

PHP 註解應該遵循 PHPDoc 的標準撰寫

成員變數 (Member)

成員變數只的是 Class 內的成員變數,我們都會要求替成員變數增加註解說明。通常 Function 的變數除非太特別否則都不需要特別註解說明。

1
2
3
4
/**
* 成員變數說明
* @type {型態}
*/

Example

1
2
3
4
5
/**
* 使用者ID
* @type {String}
*/
$userId = 'Hello';

函數、方法 (Function, Method)

1
2
3
4
5
6
7
/**
* 函數用途說明
* @param 引數型態 引數名稱 引數說明
* @option 引數選項型態 引數選項名稱 引數選項說明
* @uses 全域變數 全域變數說明
* @returns 回傳值型態 回傳值說明
*/

Example

1
2
3
4
5
6
7
8
9
10
11
12
/**
* 取得使用者
* @param int userId 使用者ID
* @param object options 其他選項
* @option string options['query'] 查詢關鍵字
* @uses $_POST['role_id'] 從前端以POST取得角色ID
* @returns object 使用者資料
*/
function getUser($userId, $options){
//do something
return $user;
};

Database

  • 禁止使用 Table Join。
  • 禁止使用 Oracle Trigger。
  • 禁止將查詢資料庫的 SQL 放在迴圈中查詢

    SQL 撰寫

  • 屬於 SQL 語法使用大寫 (SELECT, WHERE, INSERT etc..)
  • 屬於使用者自己定義的使用小寫 (表名 table name, 欄位名 column name etc..)
  • 表名、欄位名前後需加上 `

Example

1
INSERT INTO `user` VALUES('a', 'b');

統一用詞

僅為舉例,不限與此。

用詞統一
最后最後
關閉取消
存儲
保存
修改
儲存
搜尋查詢
点击查看
欢迎关注公众号,感谢支持 !
0%