程式碼風格強制者
此技能確保程式碼遵循專案特定的風格慣例與模式,超越自動化 Linter 可能遺漏的檢查。
何時使用此技能
- 使用者要求進行程式碼風格審查或改善
- 確保程式碼庫的一致性
- 導入新程式碼或新貢獻者
- 提交前的程式碼審查
- 使用者提及「風格」、「一致性」、「格式化」或「慣例」
操作說明
1. 偵測專案風格指南
尋找風格設定檔:
JavaScript/TypeScript:
.eslintrc.*- ESLint 設定.prettierrc.*- Prettier 設定tsconfig.json- TypeScript 編譯器選項.editorconfig- 編輯器設定
Python:
.pylintrc、pylint.cfg- Pylintpyproject.toml- Black、isort 設定.flake8- Flake8 設定setup.cfg- 各種工具設定
Ruby:
.rubocop.yml- RuboCop 設定
Go:
go.fmt強制執行(標準).golangci.yml- GolangCI-Lint
Java:
checkstyle.xml- Checkstyle.editorconfig
通用:
CONTRIBUTING.md- 貢獻指南STYLE_GUIDE.md- 專案風格指南.editorconfig- 跨編輯器設定
使用 Glob 找出這些檔案,並使用 Read 來理解專案的風格偏好。
2. 分析現有程式碼模式
對現有程式碼進行取樣,以了解隱含慣例:
檔案組織:
- 目錄結構模式
- 檔案命名慣例(camelCase、kebab-case、snake_case)
- 匯入/匯出組織
程式碼結構:
- 類別/函式順序
- 公有 vs 私有方法位置
- 常數/變數宣告位置
格式化:
- 縮排(空格 vs 製表符、尺寸)
- 行長限制
- 空白行使用
- 註解風格
命名:
- 變數命名(camelCase、snake_case)
- 類別命名(PascalCase、大寫)
- 常數命名(UPPER_CASE 等)
- 檔案命名模式
使用 Grep 來尋找相似檔案中的常見模式。
3. 超越 Linter:檢查模式
專注於自動化工具常遺漏的風格問題:
命名一致性:
- 布林變數:
is、has、should前綴 - 事件處理器:
handle*、on*模式 - Getter/Setter:
get*、set*一致性 - 集合命名:複數 vs 單數
- 縮寫:一致的大小寫
程式碼組織:
- 相關函式歸組在一起
- 模組間一致的檔案結構
- 邏輯順序(公有先於私有等)
- 關注點分離
註解與文件:
- JSDoc/docstring 完整性
- 註解風格一致性
- TODO/FIXME 格式
- 行內 vs 區塊註解
匯入/匯出模式:
- 匯入排序(外部、內部、相對)
- 具名 vs 預設匯出
- 解構一致性
- 別名模式
錯誤處理:
- 一致的錯誤訊息格式
- 錯誤類別使用
- Try/catch 模式
- 日誌格式
型別使用(TypeScript/型別語言):
- 明確 vs 推斷型別
interfacevstype偏好- 泛型命名(T、K、V vs 描述性)
- Null/undefined 處理
4. 識別常見反模式
標記程式碼壞味道與反模式:
魔術數字:
// 壞的
if (status === 200) { }
// 好的
const HTTP_OK = 200;
if (status === HTTP_OK) { }
不一致的 null 檢查:
// 不一致
if (user === null) { }
if (!data) { }
if (typeof result === 'undefined') { }
// 一致
if (user === null) { }
if (data === null) { }
if (result === undefined) { }
巢狀三元運算子:
// 難以閱讀
const value = a ? b ? c : d : e;
// 較好
let value;
if (a) {
value = b ? c : d;
} else {
value = e;
}
過長參數列表:
# 難以維護
def create_user(name, email, age, address, phone, ...):
# 較好
def create_user(user_data: UserData):
5. 檢查專案特定慣例
尋找此專案獨有的模式:
- 特定領域的自訂命名(例如「repo」vs「repository」)
- 常見任務的首選函式庫
- 架構模式(MVC、服務層等)
- 測試檔案命名與結構
- 設定模式
閱讀 CONTRIBUTING.md、README.md 或類似文件以取得明確指南。
6. 產生風格建議
對於每個問題,提供:
現有程式碼:
function getData(id) {
const d = fetch('/api/users/' + id);
return d;
}
問題:
- 不一致的命名(
getDatavs 其他函式使用fetch*) - 單字母變數名稱(
d) - 字串串接而非使用樣板字面值
建議:
function fetchUser(id) {
const userData = fetch(`/api/users/${id}`);
return userData;
}
7. 排定問題優先順序
按影響程度排序:
高優先級(一致性):
- 相似函式間的命名不一致
- 混合縮排或格式化
- 不一致的錯誤處理
中優先級(可讀性):
- 魔術數字/字串
- 不明確的變數名稱
- 缺少文件
低優先級(值得擁有):
- 註解格式化
- 匯入排序
- 多餘空白行
8. 建議自動化工具
推薦用於強制執行風格工具:
JavaScript/TypeScript:
npm install --save-dev prettier eslint
npx prettier --write .
npx eslint --fix .
Python:
pip install black isort flake8
black .
isort .
Go:
go fmt ./...
golangci-lint run
Ruby:
gem install rubocop
rubocop -a
9. 建立或更新 EditorConfig
如果缺少,建議建立 .editorconfig:
root = true
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
[*.{js,ts,jsx,tsx}]
indent_style = space
indent_size = 2
[*.py]
indent_style = space
indent_size = 4
[*.go]
indent_style = tab
10. 風格審查檢查清單
審查程式碼風格時:
- 命名遵循專案慣例
- 縮排與格式化一致
- 匯入組織得當
- 必要處有註解,不過多
- 無魔術數字或字串
- 錯誤處理一致
- 檔案組織符合專案結構
- 無明顯的程式碼壞味道
- 型別註解一致(若適用)
- 測試遵循測試慣例
最佳實踐
- 一致性優於完美:遵循現有模式,即使並非理想
- 記錄決策:為模棱兩可的情況添加風格指南
- 儘可能自動化:使用 Prettier、Black、gofmt 等
- 務實行事:不要為了風格重構運作中的程式碼
- 團隊共識:對重要的風格取得共識
- 漸進式改善:只修改涉及到的檔案中的風格,而非一次全部修改
- 可讀性優先:風格服務於可讀性,而非反過來
常見風格衝突
製表符 vs 空格
- 檢查
.editorconfig或現有檔案 - 有疑慮時,使用專案多數
引號風格(單引號 vs 雙引號)
- JavaScript:常用單引號 (
') - Python:兩者皆可,保持一致
- Go:一律雙引號 (
") - 若存在 Linter 設定,遵循之
分號(JavaScript)
- 檢查現有程式碼多數
- 若混用,建議使用 Prettier 強制執行
行長
- 常見限制:80、100、120 字元
- 檢查 Linter 設定或
.editorconfig
匯入排序
- 通常:標準函式庫、外部、內部、相對
- 使用自動化工具(isort、organize imports)
支援檔案
reference/style-guides.md:熱門風格指南連結examples/before-after.md:展示改善的程式碼範例