---
title: "程式碼標準 Coding Standard"
description: "整理前端團隊 JavaScript/TypeScript 程式碼規範，涵蓋命名原則、Git Commit 格式、魔法數字處理、短解管理等，幫助降低溝通成本提升協作效率。"
canonical_url: "https://blog.markkulab.net/post/coding-standard"
author: "Mark Ku"
author_url: "https://blog.markkulab.net/author/mark-ku"
site: "Mark Ku's Blog"
date_published: "2023-03-23 01:01:01 +0800"
category: "Frontend"
tags: ["coding-standard", "javascript", "typescript", "react", "git", "team"]
language: "zh-TW"
license: "CC BY 4.0"
license_url: "https://creativecommons.org/licenses/by/4.0/"
attribution: "轉載或引用請註明作者並附上原文連結"
---
# 程式碼標準 Coding Standard
## 前言
俗話說:”不以規矩，不能成方圓”，在許多專案開發時，最痛苦的就是閱讀他人的程式碼，因為沒有統一的一套標準，導致每個人在接手他人的程式碼時，都是痛苦萬分，軟體開發往往最大的成本在與溝通成本，人數越多時則產生的溝通成本越高，規範也是一種降低溝通成本，提昇團隊協作效率的一種方式。
但是所有制定出的規範是死的，人是活的，要懂得變通，有任何覺得不妥，缺漏或有更好的做法歡迎提出修改的要求。必竟在資訊這領域像逆水行舟，不進則退，所有方法技術管理技巧，都需與時俱進!
(參考: 台灣軟體產業的失落十年)
## JS 規範：
* eslint 、pretter 請調整一致，( ibuypwer next專案中有建立 .vscode\init.vscode-env.ps1 可以協助各位配置 eslint 及 Prettier 有一致的規範及排版 )
* 變數及方法命名方式，統一採用駝峰 ( casemel ) 工具也協助檢查
* 兩個 == 和三個=== 不同，可以精準判斷，那麼就不要用模糊判斷 => eslint 工具也協助檢查
* 命名要有意義 get 沒改值，就不要名命為 set
* 方法命名，意途要表達清晰 => ex: ( 動詞 + 名詞 ) getUserProfile
* 一個方法過長時，又做意途不同的事，請拆成不同的方法。
* 重覆兩次以上的的方法，請想辦法抽出來共用，不要複製個好幾分，最後變成7~8份，換個人接手，新需求來要改還改漏了。
* 在設計 React 時元件時，元件太大或可以共用的也麻煩請拆成元件。
* 系統要長期維護，能用 Typescript 就不要偷懶，只有在為了特殊考量情況下才可使用 Any。
* 在 React 的 template 不要做過多的邏輯處理，請先處理好資料 template 部份就只負責渲染就好。
* 三元表達式超過兩組以上，麻煩將他拆成方法或是狀態來控制，因為下個接手的人不好讀懂。
* 變數或方法命名使用英文單詞，不要縮寫，並且要保證單字拼寫正確。
* 在撰寫程式時要適時加入註解。ex: 邏輯複雜或可能不好理解的地方。
* 魔法數字，抽成 const 或 enums 集中管理。
* 能用斷路判斷，就不要用三元表達式
* 短路寫法要注意一下，如果傳入的參數是 undefined 或是 null 要在 props 給預設值或是用||給預設值 parentElement && Style.fixed) || ''
* 三元表達式如果超過兩個，以上請抽成一個方法，不然下一個不好閱讀。
* 在 React 使用 dangerouslySetInnerHTML 要特別小心，並不會像其他框架一樣會幫忙阻擋 xss 攻擊，請記得使用套件 dompurify 加密危險字元。
### Git 規範：
* 專案中無用的註解及程式碼、無用的文件（包括圖片、JS 文件、樣式文件、debugger等等）可以全部刪掉，不要提交到 Git；
* 本地測試代碼或本地個性化配置文件不要提交到 Git。
* 先 Pull 更新，再提交 Push，有衝突要先解衝突，再提交程式碼。
* 未來會有越來越多人進入團隊，Git 互蓋的狀況，還是有機會發生，在Git Commit 前，請確認都是你修改的程式 => 可以用 git tortoise。
* 新的分支一律從 staging 建立
* JIRA 單一單號Commit 格式
```
IUW-01 fix type error
```
* JIRA 多單號 Commit 格式
```
IUW-01 IUW-02 fix type error, refactor modal style
```
## 註解
程式設計師，半年前及半後年所撰寫的項目，往往能記住的人不多，有撰寫註解，可以幫助自己及團隊快速的了解此這些程式是在做些什麼，不需要每個都寫，會覺得別人可能看不懂或邏輯過於複雜麻煩寫一下。
寫不寫註解，其實沒有絕對，我熟知像知名外商公司，他們公司就是盡量避免撰寫註解，認為撰寫註解也需花額外的時間成本維護，也常常發生寫了功能，忘了修改註解，而造成一些意外，但這些前提是建立在公司的規範及團隊的水平趨近一致才比較適合。但現階段公司還在起步，我的建議複雜不好懂的地方，仍需撰寫註解。
## Hard Code(寫死)
指的是在軟體實作上，把輸出或輸入的相關參數（例如：路徑、輸出的形式或格式）直接以常數的方式書寫在程式中，這種寫法相當的不好，且系統上線後，未來要擴充會相當困難，因此在未必要狀況下，請勿將程式碼寫死，保留一定的彈性，寫死的狀況也並非完全只有缺陷，如只是應付某特定需求，不影響主架構的情況下，利用寫死也是一種縮短開發時間的方法，如有必要寫死，可以的話請先拿出來和同事討論，或是找找那邊有動態資料可以拿，真的不行在寫死。
## 解決魔法數字的小技巧
程式設計小計巧
我常常會看到很多新人的程式會出現，在程式中Hard Code 數字或文字，反而造成下一位在閱讀不易理解魔法數字代表著為什麼?
錯誤示範:
```
If (ShippingMethodID === 7)
{
Do some thing
}
if (subItem.OptionID == 127) {
Do some thing
}
```
這樣的程式碼是不是，魔法數字對於另一個人在閱讀不容易理解，在修改時也很有可能會漏改，這邊會建議採用同一系列的用 enum方式來決解這個問題，不是同一系列就單獨用 const。
## 短解
短解，可以短期解決暫時，但因為長期就累積很多複雜問題，短解上堆疊短解，簡單問題就變複雜了，既有程式已在線上，要在花力氣改回來，讀懂，不改爆他，得付出更多的成本。
沒辦法立即改，就應該被記錄，事後回過頭和 PM 要時間把他修正。
## Commit 可以透 Git tortoise 比較程式異動差異。
alt + 下鍵可以切換到異動的地方
## 斷路判斷
```
return ({ showHeader && }
);
```
---
## 關於本文與作者
本文出自 [Mark Ku's Blog](https://blog.markkulab.net/post/coding-standard)
授權條款： [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — 轉載或引用請註明作者並附上原文連結
### 關於作者
**[Mark Ku](https://blog.markkulab.net/author/mark-ku)** — Software Solution Provider
- 10+ 年資深軟體工程師，現為 AI 應用 Builder
- 專注大型平台架構設計，從北美電商到AI SaaS訂閱收費系統
- 結合 AI Agent 與自動化，打造高效可演進的產品技術基礎
### 作者開發的免費工具
以下工具皆可免費使用：
- [免費 PDF 簽名工具](https://blog.markkulab.net/tools/pdf-sign): 線上 PDF 簽名工具，瀏覽器內完成手繪、打字、上傳簽名，可拖曳放置、縮放、下載。所有處理都在你的裝置完成，檔案不會上傳。
- [VS Code Refactory](https://blog.markkulab.net/tools/refactory): Refactory 是一款 VS Code 重構擴充套件：34 個重構動作、37 條 code smell 檢查、Code Health 儀表板、18 種語言、534 支測試。懂你的專案慣例：介面放哪、DI 註冊寫在哪、'use client' 該不該加；還會用 git 修改頻率 × 複雜度排出「該先修哪個檔案」，並一鍵把壞味道交給你自己電腦上的 Claude Code 修。免費使用，原始碼不離開你的機器。
- [DB-Kit 資料庫管理工具](https://blog.markkulab.net/tools/db-kit): DB-Kit 是一個用 Tauri + Rust + React 打造的輕量跨平台資料庫管理工具，用單一一致的介面同時管理 MySQL、MariaDB、PostgreSQL、SQL Server、Oracle、SQLite、MongoDB、Redis、Kafka、Elasticsearch 與 RabbitMQ 十一種資料來源：連線密碼以 OS keychain 加密、SSH Tunnel、完整 CRUD、視覺化查詢建構器、多結果集同時顯示、跨連線資料傳輸與比對同步、Excel / CSV 匯入匯出、執行計畫視覺化、ER 圖、排程備份、SQL 壓力測試（p50～p99 延遲百分位）、15 條規則的 SQL 審查、Kafka 訊息瀏覽與監控告警；繁中 / 英文雙語介面，內建 AI 助手（自然語言生成 SQL、AI 審查與調校建議）與命令列工具 dbk。免費開源（MIT），提供 Windows / macOS / Linux 安裝檔。
- [VS Code Super Mermaid](https://blog.markkulab.net/tools/super-mermaid): Super Mermaid 是一款 VS Code 擴充套件：開箱即用的漂亮 Mermaid 圖表，自動上色、即時預覽、滑鼠平移縮放、PNG / SVG 高解析匯出，內建 21 種範本與多種主題。免費開源（MIT）。
- [React Super Mermaid](https://blog.markkulab.net/tools/react-super-mermaid): react-super-mermaid 是一個開源 React 元件庫：一行 即可渲染漂亮的 Mermaid 圖表，內建 colorful / sketch 主題、平移縮放、圖內搜尋、SVG / PNG 高解析匯出。輕量、SSR 安全、完整 TypeScript 型別。免費開源（MIT）。
- [Jira / Confluence Super Mermaid](https://blog.markkulab.net/tools/jira-super-mermaid): Atlassian Forge app：在 Jira issue 與 Confluence 內文直接寫 Mermaid 語法，畫流程圖、時序圖、狀態機與甘特圖。11 種圖表、SVG / PNG 匯出、明暗主題、完整中日韓文字支援。取得 Runs on Atlassian 資格：圖表存在你自己的站台，app 不呼叫任何第三方服務。免費，即將上架 Atlassian Marketplace。
- [Mermaid 線上預覽](https://blog.markkulab.net/tools/mermaid-preview): 在瀏覽器裡寫 Mermaid、即時看圖，整張圖表壓進網址就能分享。免註冊、不上傳伺服器，相容 mermaid.live 的分享連結。
- [React Intl Phone Number](https://blog.markkulab.net/tools/react-intl-phone-number): react-intl-phone-number 是一個開源 React 元件：framework-agnostic、不依賴 antd，提供 E.164 進出、可搜尋國旗 / 國碼下拉、可配置驗證等級（strict / mobile-strict / loose）、可主題化 CSS 與 i18n，電話邏輯由 google-libphonenumber 驅動。輕量、完整 TypeScript 型別。免費開源（MIT）。
- [Uptime Kuma Cluster](https://blog.markkulab.net/tools/uptime-kuma-cluster): 把單機版 Uptime Kuma 改造成高可用叢集：OpenResty + Lua 智慧負載平衡、MariaDB 共享狀態、健康檢查與自動 Failover，附叢集管理 REST API，一行 Docker Compose 啟動。免費開源（MIT）。
- [特教專案](https://blog.markkulab.net/education): 為特殊教育學生製作的學習教材
### 每日 Podcast
- [科技新鮮事](https://blog.markkulab.net/category/tech-news): 每日精選 AI 與科技趨勢，透過語音摘要快速掌握最新技術動態，涵蓋 AI 應用、軟體架構、DevOps 與工程實戰。 — RSS: https://blog.markkulab.net/feed.xml
- [AI股市蝦聊](https://blog.markkulab.net/category/ai-stock-chat): 每個交易日用 AI 分析台股盤勢，以雙人對話聊當天的盤中觀察與隔日預測。 — RSS: https://blog.markkulab.net/ai-stock-chat/feed.xml
### 電子報
[訂閱電子報](https://blog.markkulab.net/subscribe) — 第一時間收到新文章通知，無垃圾信、隨時可取消訂閱。