Design Smell Detector

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

Quick Start

Detect Design Smells

# 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:

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 for detailed solutions.

5. Verify Improvements

Re-run detection to measure progress:

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:

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

Refactoring:

# ✅ 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:

# ❌ 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:

# ✅ 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:

# ❌ 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:

# ✅ 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:

# ❌ 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:

# ✅ 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:

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

Interface Abstraction:

# Depend on abstractions, not implementations
from abc import ABC, abstractmethod

class PaymentGateway(ABC):
    @abstractmethod
    def charge(self, amount):
        pass

class PaymentProcessor:
    def __init__(self, gateway: PaymentGateway):
        self.gateway = gateway

Improve Cohesion

Extract Class:

# Split into focused classes
class User:
    # User data and behavior

class UserRepository:
    # Database operations

class EmailService:
    # Email operations

Move Method:

# Move method to appropriate class
class Account:
    def get_formatted_balance(self):  # Moved from reporter
        return f"${self.balance:.2f}"

Reduce Complexity

Extract Method:

# Break complex method into smaller ones
def process_order(order):
    validate_order(order)
    calculate_total(order)
    save_order(order)

Replace Conditional with Polymorphism:

# Use inheritance instead of conditionals
class Customer:
    def calculate_price(self, base_price):
        return base_price

class PremiumCustomer(Customer):
    def calculate_price(self, base_price):
        return base_price * 0.9

For comprehensive refactoring strategies, see refactoring_strategies.md.

Metrics and Thresholds

Detection Thresholds

Key Metrics

LCOM (Lack of Cohesion of Methods):

• •Measures how methods share instance variables
• •Range: 0.0 (high cohesion) to 1.0 (low cohesion)
• •Lower is better

Cyclomatic Complexity:

• •Number of linearly independent paths
• •Each if/while/for adds 1
• •Lower is better (< 10)

Fan-out (Coupling):

• •Number of dependencies
• •Lower is better (< 10)

Design Smell Catalog

For complete descriptions, examples, and solutions for all design smells, see smell_catalog.md.

Includes:

• •Coupling Smells: High coupling, Feature Envy, Inappropriate Intimacy
• •Cohesion Smells: Low cohesion, God Class
• •Complexity Smells: High complexity, Long Method
• •Size Smells: Long Parameter List, Large Module
• •Encapsulation Smells: Data Class, Exposed Internal State

Best Practices

1. Detect Regularly

Integrate into workflow:

# Pre-commit hook
python scripts/detect_smells.py src/

# CI/CD pipeline
make check-design-smells

2. Track Metrics Over Time

Monitor trends:

Sprint 1: 15 God classes, 45 long methods
Sprint 2: 12 God classes, 38 long methods
Sprint 3: 8 God classes, 25 long methods

3. Prioritize Strategically

Focus on:

• •Code changed frequently
• •Critical business logic
• •High-impact areas

4. Refactor Incrementally

• •Small, safe changes
• •Run tests after each change
• •Commit frequently

5. Measure Improvements

Before/after metrics:

Before: LCOM = 0.85 (low cohesion)
After:  LCOM = 0.25 (high cohesion)

Common Scenarios

Scenario 1: Legacy Codebase Modernization

Goal: Identify technical debt in legacy system

Approach:

1. •Run smell detection on entire codebase
2. •Generate metrics report
3. •Identify top 10 worst files
4. •Create refactoring backlog
5. •Tackle incrementally

Scenario 2: Code Review Enhancement

Goal: Automated design quality checks in PR reviews

Approach:

1. •Add smell detection to CI pipeline
2. •Fail build if critical smells introduced
3. •Report metrics in PR comments
4. •Require fixes before merge

Scenario 3: Architecture Assessment

Goal: Evaluate system architecture quality

Approach:

1. •Detect coupling and cohesion issues
2. •Identify God classes and large modules
3. •Analyze dependency structure
4. •Recommend architectural improvements

Integration with Development Workflow

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

python scripts/detect_smells.py src/
if [ $? -ne 0 ]; then
    echo "Critical design smells detected. Commit aborted."
    exit 1
fi

CI/CD Pipeline

# .github/workflows/quality.yml
name: Design Quality Check

on: [push, pull_request]

jobs:
  check-smells:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Detect design smells
        run: python scripts/detect_smells.py src/

      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: smell-report
          path: smell-report.json

IDE Integration

Most IDEs support similar analysis through plugins:

• •PyCharm: Built-in inspections for coupling/cohesion
• •VS Code: Python linting extensions
• •SonarLint: Real-time smell detection

Troubleshooting

False Positives

Problem: Legitimate design flagged as smell

Solution:

• •Understand context and constraints
• •Consider if threshold should be adjusted
• •Document reasons for exception

Overwhelming Results

Problem: Too many smells to address

Solution:

• •Filter by severity (critical first)
• •Focus on frequently changed code
• •Set incremental goals

Refactoring Breaks Tests

Problem: Tests fail after refactoring

Solution:

• •Ensure comprehensive test coverage first
• •Refactor incrementally
• •Run tests after each small change

Reference Documentation

Design Smell Catalog

See smell_catalog.md for:

• •Complete smell definitions
• •Detection criteria and thresholds
• •Code examples (before/after)
• •Metrics explanations (LCOM, cyclomatic complexity, fan-out)
• •All coupling, cohesion, complexity, size, and encapsulation smells

Refactoring Strategies

See refactoring_strategies.md for:

• •Coupling reduction strategies (DI, interfaces, facades)
• •Cohesion improvement (extract class, move method)
• •Complexity reduction (extract method, polymorphism)
• •Size reduction (split classes, parameter objects)
• •Encapsulation improvement
• •Refactoring workflow and best practices
• •Anti-patterns to avoid
• •Success metrics