design-smell-detector

# Design Smell Detector

Identify and address design quality issues in code through automated smell detection and refactoring guidance.

## Quick Start

### Detect Design Smells

```bash
# Analyze a single file
python scripts/detect_smells.py src/app.py

# Analyze entire directory
python scripts/detect_smells.py src/

# Output as JSON
python scripts/detect_smells.py src/ --format json
```

### Example Output

```
Found 5 design smell(s): 1 critical, 3 major, 1 minor

CRITICAL ISSUES:
  🔴 src/services.py:45 - God Class
     Class 'UserManager' has 25 methods (threshold: 20)
     💡 Split into multiple smaller, focused classes

MAJOR ISSUES:
  🟠 src/models.py:120 - Low Cohesion
     Class 'Order' has low cohesion (score: 0.25)
     💡 Group related methods/attributes or split class

  🟠 src/utils.py:89 - Long Method
     Method 'process_order' has 67 lines (threshold: 50)
     💡 Extract smaller methods or refactor
```

## Design Smells Detected

### Coupling Smells

**High Coupling**: Too many dependencies
- Module imports > 20
- Constructor dependencies > 10
- Changes cascade across classes

**Feature Envy**: Method uses other class more than own
- External access > internal access
- Method should move to envied class

**Inappropriate Intimacy**: Classes too tightly coupled
- Accessing private fields of other classes
- Excessive use of getters/setters

### Cohesion Smells

**Low Cohesion**: Class members unrelated
- LCOM (Lack of Cohesion) > 0.7
- Methods don't share instance variables
- Class has multiple responsibilities

**God Class**: Class knows/does too much
- Methods > 20
- Attributes > 15
- Lines of code > 500

### Complexity Smells

**High Cyclomatic Complexity**: Too many decision points
- Complexity > 10
- Deeply nested conditionals
- Many if/else, loops

**Long Method**: Method too long
- Lines of code > 50
- Multiple responsibilities
- Hard to understand

### Size Smells

**Long Parameter List**: Too many parameters
- Parameters > 5
- Related parameters not grouped
- Method signature hard to understand

**Large Module**: Module too large
- Classes > 20
- Lines of code > 1000
- Multiple responsibilities

### Encapsulation Smells

**Data Class**: Only data, no behavior
- Only getters/setters
- No business logic
- Missing encapsulation

**Exposed Internal State**: Implementation details exposed
- Public mutable fields
- Returns references to internal collections
- Breaks encapsulation

## Detection Workflow

### 1. Run Detection

Analyze codebase for design smells:

```bash
python scripts/detect_smells.py src/
```

### 2. Review Results

Examine detected smells by severity:
- **Critical**: God classes, severe coupling issues
- **Major**: Low cohesion, long methods, high complexity
- **Minor**: Long parameter lists, feature envy

### 3. Prioritize Refactoring

Focus on:
- Critical issues first
- Frequently changed code
- High-impact, low-effort improvements

### 4. Apply Refactoring

Use refactoring strategies based on smell type.

See **[refactoring_strategies.md](references/refactoring_strategies.md)** for detailed solutions.

### 5. Verify Improvements

Re-run detection to measure progress:

```bash
python scripts/detect_smells.py src/
```

Compare metrics before/after.

## Common Design Smells

### God Class

**Symptoms**:
- Too many methods (>20)
- Too many attributes (>15)
- Low cohesion
- Multiple responsibilities

**Example**:
```python
# ❌ God Class
class Application:
    # 30+ methods handling:
    # - User management
    # - Order processing
    # - Payment handling
    # - Reporting
    # - Email notifications
    # - File operations
    pass
```

**Refactoring**:
```python
# ✅ Split by responsibility
class UserManager:
    pass

class OrderProcessor:
    pass

class PaymentHandler:
    pass

class ReportGenerator:
    pass
```

### High Coupling

**Symptoms**:
- Too many imports (>20)
- Too many constructor dependencies
- Changes cascade across classes

**Example**:
```python
# ❌ High coupling
class UserService:
    def __init__(self):
        self.db = Database()
        self.cache = Cache()
        self.logger = Logger()
        self.validator = Validator()
        self.email = EmailService()
        self.sms = SMSService()
        # ... many more
```

**Refactoring**:
```python
# ✅ Dependency injection
class UserService:
    def __init__(self, db, logger, notifier):
        self.db = db
        self.logger = logger
        self.notifier = notifier  # Abstraction
```

### Low Cohesion

**Symptoms**:
- Methods don't share attributes
- Class does unrelated things
- LCOM score > 0.7

**Example**:
```python
# ❌ Low cohesion
class UserManager:
    def create_user(self):
        pass

    def send_email(self):
        pass

    def log_activity(self):
        pass

    def calculate_discount(self):
        pass
```

**Refactoring**:
```python
# ✅ High cohesion - focused classes
class UserRepository:
    def create_user(self):
        pass

class EmailService:
    def send_email(self):
        pass

class ActivityLogger:
    def log_activity(self):
        pass
```

### Long Method

**Symptoms**:
- Method > 50 lines
- Multiple responsibilities
- Hard to understand

**Example**:
```python
# ❌ Long method (100+ lines)
def process_order(order):
    # Validate (20 lines)
    # Calculate price (15 lines)
    # Save to DB (10 lines)
    # Send email (20 lines)
    # Update stats (10 lines)
    # Log activity (15 lines)
    pass
```

**Refactoring**:
```python
# ✅ Extract methods
def process_order(order):
    validate_order(order)
    total = calculate_total(order)
    save_order(order, total)
    send_confirmation(order)
    update_statistics()
    log_activity(order)
```

## Refactoring Strategies

### Reduce Coupling

**Dependency Injection**:
```python
# Inject dependencies instead of creating them
class OrderService:
    def __init__(self, db, logger):
        self.db = db
        self.logger = logger
```

**Interface Abstraction**:
```python
# Depend on abstractions,