517 lines
11 KiB
Markdown
517 lines
11 KiB
Markdown
---
|
||
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. **代码坏味道识别**：参考常见问题
|
||
|
||
告诉我需要审查的代码，我会帮你识别问题并提供改进建议！
|