youhua
This commit is contained in:
516
.agents/skills/clean-code/SKILL.md
Normal file
516
.agents/skills/clean-code/SKILL.md
Normal file
@@ -0,0 +1,516 @@
|
||||
---
|
||||
name: clean-code
|
||||
description: Clean Code 代码质量审查和重构指南。用于代码审查、重构、提升代码质量、减少技术债务。触发词：代码审查、clean code、重构、代码质量、技术债务、代码规范。
|
||||
---
|
||||
|
||||
# Clean Code 技能
|
||||
|
||||
帮助编写高质量、可维护、可读性强的代码。
|
||||
|
||||
## 核心原则
|
||||
|
||||
### 1. 有意义的命名
|
||||
```typescript
|
||||
// ❌ 坏
|
||||
const d = new Date();
|
||||
const ymd = date.split('-');
|
||||
|
||||
// ✅ 好
|
||||
const currentDate = new Date();
|
||||
const [year, month, day] = date.split('-');
|
||||
```
|
||||
|
||||
**规则：**
|
||||
- 使用描述性名称，避免缩写
|
||||
- 名称应该表达意图
|
||||
- 避免误导性名称
|
||||
- 做有意义的区分（不是 a1, a2）
|
||||
- 使用可搜索的名称
|
||||
- 类名用名词，方法名用动词
|
||||
|
||||
### 2. 函数
|
||||
```typescript
|
||||
// ❌ 坏 - 做太多事
|
||||
function processUser(user: User) {
|
||||
// 验证
|
||||
if (!user.email) throw new Error('Email required');
|
||||
if (!user.name) throw new Error('Name required');
|
||||
|
||||
// 保存
|
||||
database.save(user);
|
||||
|
||||
// 发送邮件
|
||||
emailService.send(user.email, 'Welcome!');
|
||||
|
||||
// 记录日志
|
||||
logger.log(`User ${user.name} created`);
|
||||
}
|
||||
|
||||
// ✅ 好 - 单一职责
|
||||
function validateUser(user: User): void {
|
||||
if (!user.email) throw new Error('Email required');
|
||||
if (!user.name) throw new Error('Name required');
|
||||
}
|
||||
|
||||
function saveUser(user: User): void {
|
||||
database.save(user);
|
||||
}
|
||||
|
||||
function sendWelcomeEmail(user: User): void {
|
||||
emailService.send(user.email, 'Welcome!');
|
||||
}
|
||||
|
||||
function logUserCreation(user: User): void {
|
||||
logger.log(`User ${user.name} created`);
|
||||
}
|
||||
|
||||
function processUser(user: User) {
|
||||
validateUser(user);
|
||||
saveUser(user);
|
||||
sendWelcomeEmail(user);
|
||||
logUserCreation(user);
|
||||
}
|
||||
```
|
||||
|
||||
**规则：**
|
||||
- 函数应该小（<20行）
|
||||
- 只做一件事
|
||||
- 每个函数一个抽象层级
|
||||
- 使用描述性名称
|
||||
- 函数参数越少越好（理想0-3个）
|
||||
- 避免副作用
|
||||
- 分隔指令与询问
|
||||
|
||||
### 3. 注释
|
||||
```typescript
|
||||
// ❌ 坏 - 多余的注释
|
||||
// 检查用户是否已激活
|
||||
if (user.isActive) { ... }
|
||||
|
||||
// ✅ 好 - 代码自解释
|
||||
if (user.isActive) { ... }
|
||||
|
||||
// ✅ 好 - 解释为什么
|
||||
// 使用 setTimeout 而不是 setInterval 避免重叠执行
|
||||
setTimeout(processQueue, 1000);
|
||||
```
|
||||
|
||||
**规则：**
|
||||
- 好的代码是自解释的
|
||||
- 注释不能弥补糟糕的代码
|
||||
- 用代码表达意图
|
||||
- 好的注释：法律信息、解释意图、警示、TODO
|
||||
- 坏的注释：喃喃自语、多余的、误导的、注释掉的代码
|
||||
|
||||
### 4. 格式
|
||||
```typescript
|
||||
// ❌ 坏
|
||||
export class User{constructor(private name:string,private age:number){}
|
||||
getName(){return this.name;}}
|
||||
|
||||
// ✅ 好
|
||||
export class User {
|
||||
constructor(
|
||||
private name: string,
|
||||
private age: number
|
||||
) {}
|
||||
|
||||
getName(): string {
|
||||
return this.name;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**规则：**
|
||||
- 垂直格式：概念之间用空行分隔
|
||||
- 水平格式：行宽<120字符
|
||||
- 缩进：统一使用2或4空格
|
||||
- 团队规则：遵循项目既定风格
|
||||
|
||||
### 5. 对象和数据结构
|
||||
```typescript
|
||||
// ❌ 坏 - 暴露内部结构
|
||||
class User {
|
||||
public name: string;
|
||||
public age: number;
|
||||
}
|
||||
|
||||
// ✅ 好 - 隐藏实现
|
||||
class User {
|
||||
private _name: string;
|
||||
private _age: number;
|
||||
|
||||
get name(): string {
|
||||
return this._name;
|
||||
}
|
||||
|
||||
set age(value: number) {
|
||||
if (value < 0) throw new Error('Invalid age');
|
||||
this._age = value;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**规则：**
|
||||
- 数据抽象：隐藏实现
|
||||
- 数据、对象的反对称性
|
||||
- 得墨忒耳定律：模块不应知道它操作对象的内部细节
|
||||
|
||||
### 6. 错误处理
|
||||
```typescript
|
||||
// ❌ 坏 - 返回 null
|
||||
function getUser(id: string): User | null {
|
||||
return database.find(id);
|
||||
}
|
||||
|
||||
// ✅ 好 - 抛出异常
|
||||
function getUser(id: string): User {
|
||||
const user = database.find(id);
|
||||
if (!user) throw new UserNotFoundError(id);
|
||||
return user;
|
||||
}
|
||||
|
||||
// ✅ 好 - 使用 Special Case 模式
|
||||
class NullUser implements User {
|
||||
name = 'Guest';
|
||||
age = 0;
|
||||
}
|
||||
```
|
||||
|
||||
**规则：**
|
||||
- 使用异常而非返回码
|
||||
- 先写 Try-Catch-Finally
|
||||
- 给出异常的上下文
|
||||
- 别返回 null 值
|
||||
- 别传递 null 值
|
||||
|
||||
### 7. 边界
|
||||
```typescript
|
||||
// ❌ 坏 - 直接依赖第三方类
|
||||
import { Map } from 'third-party-lib';
|
||||
|
||||
class UserCollection {
|
||||
private users: Map<string, User>;
|
||||
}
|
||||
|
||||
// ✅ 好 - 使用适配器模式
|
||||
interface UserMap {
|
||||
get(key: string): User;
|
||||
set(key: string, user: User): void;
|
||||
}
|
||||
|
||||
class ThirdPartyUserMap implements UserMap {
|
||||
private map: Map<string, User>;
|
||||
|
||||
get(key: string): User {
|
||||
return this.map.get(key);
|
||||
}
|
||||
|
||||
set(key: string, user: User): void {
|
||||
this.map.set(key, user);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**规则：**
|
||||
- 隐藏第三方代码
|
||||
- 使用适配器模式
|
||||
- 边界处的代码需要清晰的分割和测试
|
||||
|
||||
### 8. 单元测试
|
||||
```typescript
|
||||
// ❌ 坏 - 不清晰的测试
|
||||
test('user', () => {
|
||||
const u = new User('John', 25);
|
||||
expect(u.getName()).toBe('John');
|
||||
expect(u.getAge()).toBe(25);
|
||||
});
|
||||
|
||||
// ✅ 好 - BUILD-OPERATE-CHECK 模式
|
||||
test('shouldReturnUserName', () => {
|
||||
// BUILD
|
||||
const user = new User('John', 25);
|
||||
|
||||
// OPERATE
|
||||
const name = user.getName();
|
||||
|
||||
// CHECK
|
||||
expect(name).toBe('John');
|
||||
});
|
||||
|
||||
// ✅ 好 - Given-When-Then 模式
|
||||
test('shouldReturnUserName', () => {
|
||||
// Given
|
||||
const user = new User('John', 25);
|
||||
|
||||
// When
|
||||
const name = user.getName();
|
||||
|
||||
// Then
|
||||
expect(name).toBe('John');
|
||||
});
|
||||
```
|
||||
|
||||
**规则：**
|
||||
- F.I.R.S.T 原则：
|
||||
- Fast（快速）
|
||||
- Independent（独立）
|
||||
- Repeatable（可重复）
|
||||
- Self-Validating（自验证）
|
||||
- Timely（及时）
|
||||
- 每个测试一个断言
|
||||
- 单一概念
|
||||
- 测试代码和生产代码一样重要
|
||||
|
||||
### 9. 类
|
||||
```typescript
|
||||
// ❌ 坏 - 大类
|
||||
class UserManager {
|
||||
createUser() {}
|
||||
deleteUser() {}
|
||||
updateUser() {}
|
||||
sendEmail() {}
|
||||
validateEmail() {}
|
||||
generateReport() {}
|
||||
}
|
||||
|
||||
// ✅ 好 - 单一职责
|
||||
class UserService {
|
||||
create(user: User) {}
|
||||
delete(id: string) {}
|
||||
update(user: User) {}
|
||||
}
|
||||
|
||||
class EmailService {
|
||||
send(email: string, content: string) {}
|
||||
validate(email: string): boolean {}
|
||||
}
|
||||
|
||||
class ReportService {
|
||||
generate(userId: string): Report {}
|
||||
}
|
||||
```
|
||||
|
||||
**规则：**
|
||||
- 类应该小
|
||||
- 单一职责原则（SRP）
|
||||
- 内聚性：方法和数据互相依赖
|
||||
- 保持内聚性就会得到许多短小的类
|
||||
|
||||
### 10. 系统
|
||||
```typescript
|
||||
// ❌ 坏 - 硬编码依赖
|
||||
class UserService {
|
||||
private db = new Database(); // 硬编码
|
||||
}
|
||||
|
||||
// ✅ 好 - 依赖注入
|
||||
class UserService {
|
||||
constructor(private db: Database) {}
|
||||
}
|
||||
|
||||
// ✅ 好 - 工厂模式
|
||||
class ServiceFactory {
|
||||
static createUserService(): UserService {
|
||||
return new UserService(new Database());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**规则：**
|
||||
- 分离构造和使用
|
||||
- 依赖注入
|
||||
- 扩充：AOP（面向切面编程）
|
||||
- 测试驱动系统架构
|
||||
|
||||
## 代码审查清单
|
||||
|
||||
### 命名
|
||||
- [ ] 变量名是否描述了其用途？
|
||||
- [ ] 函数名是否描述了其行为？
|
||||
- [ ] 类名是否描述了其职责？
|
||||
- [ ] 名称是否一致？
|
||||
|
||||
### 函数
|
||||
- [ ] 函数是否小于20行？
|
||||
- [ ] 函数是否只做一件事？
|
||||
- [ ] 函数参数是否<=3个？
|
||||
- [ ] 函数是否有副作用？
|
||||
- [ ] 函数名是否描述性？
|
||||
|
||||
### 结构
|
||||
- [ ] 代码是否有清晰的层次结构？
|
||||
- [ ] 类是否遵循单一职责原则？
|
||||
- [ ] 是否有重复代码？
|
||||
- [ ] 依赖是否清晰？
|
||||
|
||||
### 测试
|
||||
- [ ] 是否有足够的测试覆盖？
|
||||
- [ ] 测试是否快速？
|
||||
- [ ] 测试是否独立？
|
||||
- [ ] 测试是否清晰？
|
||||
|
||||
### 错误处理
|
||||
- [ ] 是否处理了所有可能的错误？
|
||||
- [ ] 错误信息是否清晰？
|
||||
- [ ] 是否避免了返回 null？
|
||||
|
||||
## 重构技巧
|
||||
|
||||
### 提取方法
|
||||
```typescript
|
||||
// Before
|
||||
function printOwing(invoice: Invoice) {
|
||||
let outstanding = 0;
|
||||
|
||||
// 打印横幅
|
||||
console.log('***********************');
|
||||
console.log('*** Customer Owes ***');
|
||||
console.log('***********************');
|
||||
|
||||
// 计算未付款
|
||||
for (const order of invoice.orders) {
|
||||
outstanding += order.amount;
|
||||
}
|
||||
|
||||
// 打印详情
|
||||
console.log(`name: ${invoice.customer}`);
|
||||
console.log(`amount: ${outstanding}`);
|
||||
}
|
||||
|
||||
// After
|
||||
function printOwing(invoice: Invoice) {
|
||||
printBanner();
|
||||
const outstanding = calculateOutstanding(invoice);
|
||||
printDetails(invoice, outstanding);
|
||||
}
|
||||
|
||||
function printBanner() {
|
||||
console.log('***********************');
|
||||
console.log('*** Customer Owes ***');
|
||||
console.log('***********************');
|
||||
}
|
||||
|
||||
function calculateOutstanding(invoice: Invoice): number {
|
||||
return invoice.orders.reduce((sum, order) => sum + order.amount, 0);
|
||||
}
|
||||
|
||||
function printDetails(invoice: Invoice, outstanding: number) {
|
||||
console.log(`name: ${invoice.customer}`);
|
||||
console.log(`amount: ${outstanding}`);
|
||||
}
|
||||
```
|
||||
|
||||
### 内联方法
|
||||
```typescript
|
||||
// Before
|
||||
function getRating(driver: Driver): number {
|
||||
return moreThanFiveLateDeliveries(driver) ? 2 : 1;
|
||||
}
|
||||
|
||||
function moreThanFiveLateDeliveries(driver: Driver): boolean {
|
||||
return driver.numberOfLateDeliveries > 5;
|
||||
}
|
||||
|
||||
// After
|
||||
function getRating(driver: Driver): number {
|
||||
return driver.numberOfLateDeliveries > 5 ? 2 : 1;
|
||||
}
|
||||
```
|
||||
|
||||
### 提取变量
|
||||
```typescript
|
||||
// Before
|
||||
if (platform.toUpperCase().indexOf('MAC') > -1 &&
|
||||
browser.toUpperCase().indexOf('IE') > -1 &&
|
||||
wasInitialized() && resize > 0) {
|
||||
// do something
|
||||
}
|
||||
|
||||
// After
|
||||
const isMacOs = platform.toUpperCase().indexOf('MAC') > -1;
|
||||
const isIE = browser.toUpperCase().indexOf('IE') > -1;
|
||||
const wasResized = resize > 0;
|
||||
|
||||
if (isMacOs && isIE && wasInitialized() && wasResized) {
|
||||
// do something
|
||||
}
|
||||
```
|
||||
|
||||
### 分解条件
|
||||
```typescript
|
||||
// Before
|
||||
if (date.before(SUMMER_START) || date.after(SUMMER_END)) {
|
||||
charge = quantity * winterRate + winterServiceCharge;
|
||||
} else {
|
||||
charge = quantity * summerRate;
|
||||
}
|
||||
|
||||
// After
|
||||
if (isSummer(date)) {
|
||||
charge = summerCharge(quantity);
|
||||
} else {
|
||||
charge = winterCharge(quantity);
|
||||
}
|
||||
|
||||
function isSummer(date: Date): boolean {
|
||||
return !date.before(SUMMER_START) && !date.after(SUMMER_END);
|
||||
}
|
||||
|
||||
function summerCharge(quantity: number): number {
|
||||
return quantity * summerRate;
|
||||
}
|
||||
|
||||
function winterCharge(quantity: number): number {
|
||||
return quantity * winterRate + winterServiceCharge;
|
||||
}
|
||||
```
|
||||
|
||||
### 以多态取代条件
|
||||
```typescript
|
||||
// Before
|
||||
function calculatePay(employee: Employee): number {
|
||||
switch (employee.type) {
|
||||
case 'ENGINEER':
|
||||
return employee.monthlySalary;
|
||||
case 'SALESMAN':
|
||||
return employee.monthlySalary + employee.commission;
|
||||
case 'MANAGER':
|
||||
return employee.monthlySalary + employee.bonus;
|
||||
default:
|
||||
throw new Error('Invalid employee type');
|
||||
}
|
||||
}
|
||||
|
||||
// After
|
||||
abstract class Employee {
|
||||
abstract calculatePay(): number;
|
||||
}
|
||||
|
||||
class Engineer extends Employee {
|
||||
calculatePay(): number {
|
||||
return this.monthlySalary;
|
||||
}
|
||||
}
|
||||
|
||||
class Salesman extends Employee {
|
||||
calculatePay(): number {
|
||||
return this.monthlySalary + this.commission;
|
||||
}
|
||||
}
|
||||
|
||||
class Manager extends Employee {
|
||||
calculatePay(): number {
|
||||
return this.monthlySalary + this.bonus;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 使用方法
|
||||
|
||||
1. **代码审查时**：参考清单逐项检查
|
||||
2. **重构时**：应用重构技巧
|
||||
3. **新功能开发时**：遵循核心原则
|
||||
4. **代码坏味道识别**：参考常见问题
|
||||
|
||||
告诉我需要审查的代码，我会帮你识别问题并提供改进建议！
|
||||
Reference in New Issue
Block a user