code-quality

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

代码质量检查知识库

Code Quality Check Knowledge Base

本技能提供自动化的代码质量检查，识别常见问题并提供改进建议。

This skill provides automated code quality checks, identifies common issues, and offers improvement recommendations.

检查维度

Check Dimensions

1. 代码复杂度

1. Code Complexity

圈复杂度 (Cyclomatic Complexity)

Cyclomatic Complexity

衡量代码中独立路径的数量。

阈值建议:

1-10: 简单，容易理解和测试
11-20: 中等复杂，需要注意
21-50: 复杂，建议重构
50+: 非常复杂，必须重构

降低复杂度的方法:

// ❌ 高复杂度
func ProcessOrder(order Order) error {
    if order.Status == "pending" {
        if order.Amount > 1000 {
            if order.User.IsVIP {
                // 复杂的逻辑
            } else {
                // 另一个复杂逻辑
            }
        } else {
            // 更多逻辑
        }
    } else if order.Status == "confirmed" {
        // 更多嵌套
    }
    return nil
}

// ✅ 降低复杂度：提取方法
func ProcessOrder(order Order) error {
    if order.Status == "pending" {
        return processPendingOrder(order)
    }
    if order.Status == "confirmed" {
        return processConfirmedOrder(order)
    }
    return nil
}

func processPendingOrder(order Order) error {
    if order.Amount > 1000 {
        return processLargeOrder(order)
    }
    return processSmallOrder(order)
}

Measures the number of independent paths in code.

Threshold Recommendations:

1-10: Simple, easy to understand and test
11-20: Moderately complex, requires attention
21-50: Complex, refactoring recommended
50+: Extremely complex, refactoring mandatory

Methods to Reduce Complexity:

// ❌ High Complexity
func ProcessOrder(order Order) error {
    if order.Status == "pending" {
        if order.Amount > 1000 {
            if order.User.IsVIP {
                // Complex logic
            } else {
                // Another complex logic
            }
        } else {
            // More logic
        }
    } else if order.Status == "confirmed" {
        // More nesting
    }
    return nil
}

// ✅ Reduce Complexity: Extract Methods
func ProcessOrder(order Order) error {
    if order.Status == "pending" {
        return processPendingOrder(order)
    }
    if order.Status == "confirmed" {
        return processConfirmedOrder(order)
    }
    return nil
}

func processPendingOrder(order Order) error {
    if order.Amount > 1000 {
        return processLargeOrder(order)
    }
    return processSmallOrder(order)
}

认知复杂度 (Cognitive Complexity)

Cognitive Complexity

衡量代码的理解难度。

降低认知复杂度:

减少嵌套层级（不超过 3 层）
使用早返回（early return）
提取复杂条件为命名函数
使用卫语句（guard clauses）

// ❌ 高认知复杂度
func ValidateUser(user User) error {
    if user.Name != "" {
        if user.Email != "" {
            if user.Age >= 18 {
                return nil
            } else {
                return errors.New("age must be >= 18")
            }
        } else {
            return errors.New("email required")
        }
    } else {
        return errors.New("name required")
    }
}

// ✅ 低认知复杂度：使用卫语句
func ValidateUser(user User) error {
    if user.Name == "" {
        return errors.New("name required")
    }
    if user.Email == "" {
        return errors.New("email required")
    }
    if user.Age < 18 {
        return errors.New("age must be >= 18")
    }
    return nil
}

Measures the difficulty of understanding code.

Reduce Cognitive Complexity:

Reduce nesting levels (no more than 3 levels)
Use early return
Extract complex conditions into named functions
Use guard clauses

// ❌ High Cognitive Complexity
func ValidateUser(user User) error {
    if user.Name != "" {
        if user.Email != "" {
            if user.Age >= 18 {
                return nil
            } else {
                return errors.New("age must be >= 18")
            }
        } else {
            return errors.New("email required")
        }
    } else {
        return errors.New("name required")
    }
}

// ✅ Low Cognitive Complexity: Use Guard Clauses
func ValidateUser(user User) error {
    if user.Name == "" {
        return errors.New("name required")
    }
    if user.Email == "" {
        return errors.New("email required")
    }
    if user.Age < 18 {
        return errors.New("age must be >= 18")
    }
    return nil
}

2. 代码重复 (Code Duplication)

2. Code Duplication

检测重复

Detect Duplication

完全重复的代码块
结构相似但细节不同的代码
复制粘贴的代码

Identical code blocks
Structurally similar code with minor differences
Copy-pasted code

重复的危害

Harms of Duplication

维护成本高（修改需要多处更改）
容易引入 bug
代码库膨胀

High maintenance cost (changes needed in multiple places)
Prone to introducing bugs
Bloated codebase

消除重复

Eliminate Duplication

// ❌ 重复代码
func CreateUserOrder(user User, items []Item) error {
    total := 0.0
    for _, item := range items {
        total += item.Price * float64(item.Quantity)
    }
    discount := total * 0.1
    final := total - discount
    return saveOrder(user.ID, final)
}

func CreateGuestOrder(email string, items []Item) error {
    total := 0.0
    for _, item := range items {
        total += item.Price * float64(item.Quantity)
    }
    discount := total * 0.1
    final := total - discount
    return saveGuestOrder(email, final)
}

// ✅ 提取公共逻辑
func calculateOrderTotal(items []Item) float64 {
    total := 0.0
    for _, item := range items {
        total += item.Price * float64(item.Quantity)
    }
    discount := total * 0.1
    return total - discount
}

func CreateUserOrder(user User, items []Item) error {
    total := calculateOrderTotal(items)
    return saveOrder(user.ID, total)
}

func CreateGuestOrder(email string, items []Item) error {
    total := calculateOrderTotal(items)
    return saveGuestOrder(email, total)
}

// ❌ Duplicate Code
func CreateUserOrder(user User, items []Item) error {
    total := 0.0
    for _, item := range items {
        total += item.Price * float64(item.Quantity)
    }
    discount := total * 0.1
    final := total - discount
    return saveOrder(user.ID, final)
}

func CreateGuestOrder(email string, items []Item) error {
    total := 0.0
    for _, item := range items {
        total += item.Price * float64(item.Quantity)
    }
    discount := total * 0.1
    final := total - discount
    return saveGuestOrder(email, final)
}

// ✅ Extract Common Logic
func calculateOrderTotal(items []Item) float64 {
    total := 0.0
    for _, item := range items {
        total += item.Price * float64(item.Quantity)
    }
    discount := total * 0.1
    return total - discount
}

func CreateUserOrder(user User, items []Item) error {
    total := calculateOrderTotal(items)
    return saveOrder(user.ID, total)
}

func CreateGuestOrder(email string, items []Item) error {
    total := calculateOrderTotal(items)
    return saveGuestOrder(email, total)
}

3. 函数和方法质量

3. Function and Method Quality

函数长度

Function Length

建议: 不超过 50 行
理想: 20-30 行
过长: 考虑职责是否过多

Recommendation: No more than 50 lines
Ideal: 20-30 lines
Overly long: Check if it has too many responsibilities

参数数量

Parameter Count

理想: 0-2 个参数
可接受: 3-4 个参数
需要重构: 5+ 个参数

改进方法:

// ❌ 参数过多
func CreateUser(name, email, phone, address, city, country, zipCode string, age int) error {
    // ...
}

// ✅ 使用对象封装
type UserInfo struct {
    Name    string
    Email   string
    Phone   string
    Address Address
    Age     int
}

type Address struct {
    Street  string
    City    string
    Country string
    ZipCode string
}

func CreateUser(info UserInfo) error {
    // ...
}

Ideal: 0-2 parameters
Acceptable: 3-4 parameters
Needs refactoring: 5+ parameters

Improvement Methods:

// ❌ Too many parameters
func CreateUser(name, email, phone, address, city, country, zipCode string, age int) error {
    // ...
}

// ✅ Use object encapsulation
type UserInfo struct {
    Name    string
    Email   string
    Phone   string
    Address Address
    Age     int
}

type Address struct {
    Street  string
    City    string
    Country string
    ZipCode string
}

func CreateUser(info UserInfo) error {
    // ...
}

返回值

Return Values

明确的返回类型
错误处理清晰
避免返回 nil 导致 panic

Clear return types
Clear error handling
Avoid returning nil to prevent panic

4. 命名质量

4. Naming Quality

变量命名

Variable Naming

// ❌ 糟糕的命名
var d int // 什么的 d?
var data []byte // 太通用
var x User // 无意义

// ✅ 好的命名
var daysSinceLastLogin int
var requestBody []byte
var currentUser User

// ❌ Poor naming
var d int // What does d stand for?
var data []byte // Too generic
var x User // Meaningless

// ✅ Good naming
var daysSinceLastLogin int
var requestBody []byte
var currentUser User

函数命名

Function Naming

// ❌ 不清晰
func proc() error { ... }
func handle(d Data) { ... }

// ✅ 清晰表意
func ProcessPayment() error { ... }
func HandleUserRegistration(data RegistrationData) { ... }

// ❌ Unclear
func proc() error { ... }
func handle(d Data) { ... }

// ✅ Clear and expressive
func ProcessPayment() error { ... }
func HandleUserRegistration(data RegistrationData) { ... }

常量和配置

Constants and Configuration

// ❌ 魔术数字
if user.LoginAttempts > 5 { ... }
time.Sleep(300 * time.Second)

// ✅ 命名常量
const MaxLoginAttempts = 5
const DefaultTimeout = 300 * time.Second

if user.LoginAttempts > MaxLoginAttempts { ... }
time.Sleep(DefaultTimeout)

// ❌ Magic numbers
if user.LoginAttempts > 5 { ... }
time.Sleep(300 * time.Second)

// ✅ Named constants
const MaxLoginAttempts = 5
const DefaultTimeout = 300 * time.Second

if user.LoginAttempts > MaxLoginAttempts { ... }
time.Sleep(DefaultTimeout)

5. 注释质量

5. Comment Quality

有价值的注释

Valuable Comments

// ✅ 解释为什么
// 使用指数退避避免在服务重启时造成雷鸣般的请求
func retryWithBackoff() { ... }

// 解释业务规则
// 根据税法规定，超过 1000 元的订单需要额外审核
if order.Amount > 1000 { ... }

// ✅ Explain why
// Use exponential backoff to avoid thundering herd during service restart
func retryWithBackoff() { ... }

// Explain business rules
// According to tax regulations, orders over 1000 yuan require additional review
if order.Amount > 1000 { ... }

无价值的注释

Worthless Comments

// ❌ 重复代码内容
// 设置名称为 John
name := "John"

// 循环遍历用户
for _, user := range users { ... }

// ❌ Repeat code content
// Set name to John
name := "John"

// Loop through users
for _, user := range users { ... }

6. 错误处理质量

6. Error Handling Quality

检查点

Checkpoints

所有错误都被处理
错误消息包含上下文
使用错误包装保留堆栈
在适当的层级处理错误

// ❌ 忽略错误
file, _ := os.Open("config.json")

// ❌ 丢失上下文
return err

// ✅ 良好的错误处理
file, err := os.Open("config.json")
if err != nil {
    return fmt.Errorf("failed to open config file: %w", err)
}
defer file.Close()

All errors are handled
Error messages include context
Use error wrapping to preserve stack traces
Handle errors at appropriate levels

// ❌ Ignore error
file, _ := os.Open("config.json")

// ❌ Lose context
return err

// ✅ Good error handling
file, err := os.Open("config.json")
if err != nil {
    return fmt.Errorf("failed to open config file: %w", err)
}
defer file.Close()

7. 资源管理

7. Resource Management

文件处理

File Handling

// ✅ 使用 defer 确保关闭
file, err := os.Open("data.txt")
if err != nil {
    return err
}
defer file.Close()

// ✅ Use defer to ensure closure
file, err := os.Open("data.txt")
if err != nil {
    return err
}
defer file.Close()

并发资源

Concurrent Resources

// ✅ 使用 sync.WaitGroup
var wg sync.WaitGroup
for i := 0; i < 10; i++ {
    wg.Add(1)
    go func(n int) {
        defer wg.Done()
        // 处理
    }(i)
}
wg.Wait()

// ✅ Use sync.WaitGroup
var wg sync.WaitGroup
for i := 0; i < 10; i++ {
    wg.Add(1)
    go func(n int) {
        defer wg.Done()
        // Processing
    }(i)
}
wg.Wait()

8. 依赖管理

8. Dependency Management

耦合度

Coupling

低耦合: 模块间依赖少
高内聚: 模块内部功能相关

Low coupling: Minimal dependencies between modules
High cohesion: Functions within a module are closely related

依赖注入

Dependency Injection

// ❌ 紧耦合
type UserService struct {
    db *sql.DB // 直接依赖具体实现
}

// ✅ 依赖注入
type UserRepository interface {
    FindByID(id string) (*User, error)
    Save(user *User) error
}

type UserService struct {
    repo UserRepository // 依赖抽象
}

// ❌ Tight coupling
type UserService struct {
    db *sql.DB // Direct dependency on concrete implementation
}

// ✅ Dependency injection
type UserRepository interface {
    FindByID(id string) (*User, error)
    Save(user *User) error
}

type UserService struct {
    repo UserRepository // Depend on abstraction
}

质量指标

Quality Metrics

优先级分类

Priority Classification

P0 - 必须修复

P0 - Must Fix

未处理的错误
资源泄漏
明显的逻辑错误
安全漏洞

Unhandled errors
Resource leaks
Obvious logical errors
Security vulnerabilities

P1 - 强烈建议

P1 - Strongly Recommended

高复杂度函数（圈复杂度 > 20）
大量重复代码
过长的函数（> 100 行）
参数过多（> 5 个）

High complexity functions (Cyclomatic Complexity > 20)
Significant code duplication
Overly long functions (> 100 lines)
Too many parameters (>5)

P2 - 建议改进

P2 - Recommended Improvement

中等复杂度（圈复杂度 11-20）
命名不清晰
缺少必要注释
可以优化的性能

Moderate complexity (Cyclomatic Complexity 11-20)
Unclear naming
Missing necessary comments
Optimizable performance

P3 - 可选优化

P3 - Optional Optimization

轻微的代码风格问题
可以更好的命名
次要的重构机会

Minor code style issues
Naming that can be improved
Secondary refactoring opportunities

自动检查清单

Automated Check Checklist

在审查代码时，自动检查以下项目：

When reviewing code, automatically check the following items:

基本质量

Basic Quality

可维护性

Maintainability

函数长度合理（< 50 行）
圈复杂度可接受（< 10）
无大量重复代码
命名清晰有意义

Reasonable function length (< 50 lines)
Acceptable Cyclomatic Complexity (< 10)
No significant code duplication
Clear and meaningful naming

可读性

Readability

性能

Performance

改进建议模板

Improvement Recommendation Template

当识别到质量问题时，提供以下格式的建议：

markdown

undefined

When identifying quality issues, provide recommendations in the following format:

markdown

undefined

代码质量问题: [问题类型]

Code Quality Issue: [Issue Type]

位置: [文件名:行号]

问题: [描述问题]

严重程度: P0 / P1 / P2 / P3

影响: [说明影响]

建议修改: [提供具体的改进代码]

原因: [解释为什么要这样改]

undefined

Location: [Filename:Line Number]

Problem: [Describe the issue]

Severity: P0 / P1 / P2 / P3

Impact: [Explain the impact]

Recommended Fix: [Provide specific improved code]

Reason: [Explain why this change is needed]

undefined