web 开发规则,代码规范
目录
注意
本文最后更新于 2022-07-31,文中内容可能已过时。
精神
- 絕對不寫死程式
- 不留不要用的、垃圾程式碼
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
- 複數名詞:可以複數筆資料,回傳結果為 Array
舉例:GET/users 取得多筆使用者資料
- URL 中一律不帶 id 參數
|
|
命名
- 命名應根據內容做有意義的命名,讓後續維護人員可以顧名思義!
- 即使不會發生錯誤,程式碼英文大小寫也需明確區分。
語意
類型 | 命名規則 | 說明 |
---|---|---|
屬性 (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 的 {} 嚴禁省略。
- {} 起始一律跟在 前一個功能的尾巴,禁止分行
正確寫法
|
|
錯誤寫法
|
|
- 程式碼排版
- 任何程式碼應該以 2 個 space 為一個階層做好排版、不可使用 tab。
- 函數 (Function, Methd)
- 函數宣告時需在函數上方加上函數註解,註解應包含函數說明、引數內容 (引數型態、引數英文名稱、引數說明)、 回傳值內容 (回傳值型態、回傳值說明)
- 類 (Class)
- 一個類 (Class) 的宣告只能存在一個檔案。
- 類 (Class) 的宣告檔,檔名必須為類名。
- 其他
- 連結本地任何其他資源 (圖片、檔案、網站) 皆使用相對路徑,禁止使用絕對路徑,非本地資源除外。
HTML
程式碼撰寫
- 禁止在 HTML 使用
<style>
、<script>
,一律使用外部檔案引用方式引用 CSS、JavaScript 檔案。 - HTML 標籤需成雙成對,有頭有尾。
- 區塊標籤:
<tag></tag>
- 單標籤:
<tag />
- 禁止使用已被 HTML 捨棄的舊標籤、屬性,如:
|
|
資安禁止:
禁止使用 readonly 做為參數傳遞
其他
連結本地任何其他資源 (圖片、檔案、網站) 皆使用相對路徑,禁止使用絕對路徑,非本地資源除外。
CSS
程式碼撰寫
CSS 的定義應該獨立一個 CSS 檔案,禁止使用
<style>
或style
屬性直接在 HTML 中定義樣式。
JavaScript
程式碼撰寫
- 禁止使用 HTML 字串,一律使用 Dom 產生 HTML
- 禁止省略箭頭函數 (Arrow function) 的括弧
正確
|
|
錯誤 (這是允許的,但造成程式碼閱讀困難,故禁止)
|
|
註解
JavaScript 註解應該遵循 JSDoc 的標準撰寫
全域變數 (Global)
|
|
常數 (Constant)
|
|
Example
|
|
函數、方法 (Function, Method)
|
|
Example
|
|
PHP
前端參數取得
參數取得需透過 filter_input 函數取得,不得使用 $_GET、 $_POST
輸出到前台
參數命名必須為:全部小寫,不同單字以「_」分隔
註解
PHP 註解應該遵循 PHPDoc 的標準撰寫
成員變數 (Member)
成員變數只的是 Class 內的成員變數,我們都會要求替成員變數增加註解說明。通常 Function 的變數除非太特別否則都不需要特別註解說明。
|
|
Example
|
|
函數、方法 (Function, Method)
|
|
Example
|
|
Database
- 禁止使用 Table Join。
- 禁止使用 Oracle Trigger。
- 禁止將查詢資料庫的 SQL 放在迴圈中查詢
SQL 撰寫
- 屬於 SQL 語法使用大寫 (SELECT, WHERE, INSERT etc..)
- 屬於使用者自己定義的使用小寫 (表名 table name, 欄位名 column name etc..)
- 表名、欄位名前後需加上 `
Example
|
|
統一用詞
僅為舉例,不限與此。
用詞 | 統一 |
---|---|
最后 | 最後 |
關閉 | 取消 |
存儲 保存 修改 | 儲存 |
搜尋 | 查詢 |
Buy me a coffee~

