代码风格强制器 是做什么的?
此技能确保代码遵循项目特定的风格约定和模式,这些是自动化 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 制表符,大小)
- 行长度限制
- 空行使用
- 注释风格
命名:
- 变量命名(camelCase、snake_case)
- 类命名(PascalCase、大小写)
- 常量命名(UPPER_CASE 等)
- 文件命名模式
使用 Grep 在类似文件中查找常见模式。
3. 超越 Linter:检查模式
重点关注自动化工具常遗漏的风格问题:
命名一致性:
- 布尔变量:
is、has、should前缀 - 事件处理函数:
handle*、on*模式 - Getter/Setter:
get*、set*一致性 - 集合命名:复数 vs 单数
- 缩写:一致的大小写
代码组织:
- 相关函数分组
- 模块间一致的文件结构
- 逻辑排序(公共在前,私有在后等)
- 关注点分离
注释和文档:
- JSDoc/docstring 完整性
- 注释风格一致性
- TODO/FIXME 格式
- 行内注释与块注释
导入/导出模式:
- 导入顺序(外部、内部、相对)
- 命名导出与默认导出
- 解构一致性
- 别名模式
错误处理:
- 一致的错误消息格式
- 错误类使用
- Try/catch 模式
- 日志格式
类型使用(TypeScript/类型化语言):
- 显式类型与推断类型
interface与type的偏好- 泛型命名(T、K、V 与描述性命名)
- Null/undefined 处理
4. 识别常见反模式
标记代码异味和反模式:
魔数:
// 不好
if (status === 200) { }
// 好
const HTTP_OK = 200;
if (status === HTTP_OK) { }
不一致的空值检查:
// 不一致
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;
}
问题:
- 命名不一致(
getData与其他使用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:展示改进的代码示例