Technical Debt Management

Types of Technical Debt

Code Smells in Magento

// God Class - too many responsibilities
class OrderManager
{
    public function create() { /* ... */ }
    public function process() { /* ... */ }
    public function ship() { /* ... */ }
    public function invoice() { /* ... */ }
    public function email() { /* ... */ }
    public function refund() { /* ... */ }
    public function cancel() { /* ... */ }
    // 50+ methods
}

// Long Method
public function processOrder($orderId)
{
    // 200+ lines of code
    // Multiple responsibilities
    // Hard to test
}

// Duplicated Code
function calculateTaxA($amount) { return $amount * 0.1; }
function calculateTaxB($amount) { return $amount * 0.1; }
function calculateTaxC($amount) { return $amount * 0.1; }

Technical Debt Indicators

# Static analysis findings
vendor/bin/phpstan analyse --level=6 app/code/Vendor/ 2>&1 | grep -c "found"

# Code duplication
vendor/bin/phpcpd app/code/Vendor/

# Test coverage
vendor/bin/phpunit --coverage-text | tail -5

# Complexity metrics
vendor/bin/phpmd app/code/Vendor/ text codesize

Debt in Configuration

<!-- BAD: Deprecated method usage -->
<config>
    <global>
        <models>
            <vendor_module>
                <class>Vendor\Module\Model</class>
                <resourceModel>vendor_module/resource</resourceModel>
            </vendor_module>
        </models>
    </global>
</config>

<!-- GOOD: Modern approach -->
<!-- Use service contracts and DI -->

Key Takeaway

Technical debt includes design, code, testing, documentation, and infrastructure issues. Use static analysis tools to identify code smells and debt indicators.

Debt Metrics

# Code duplication percentage
vendor/bin/phpcpd app/code/Vendor/ --fuzzy

# cyclomatic complexity
vendor/bin/phpmd app/code/Vendor/ text codesize

# Lines of code
find app/code/Vendor/ -name '*.php' | xargs wc -l

# Test coverage
vendor/bin/phpunit --coverage-text

# PHPStan errors
vendor/bin/phpstan analyse --level=6 app/code/Vendor/ 2>&1 | tail -1

Debt Scoring

## Debt Score Calculation

Impact (1-5):
1 = Minor inconvenience
2 = Small productivity loss
3 = Moderate productivity loss
4 = Significant risk
5 = Critical risk

Effort (1-5):
1 = Trivial fix (< 1 hour)
2 = Small fix (1-4 hours)
3 = Medium fix (1-2 days)
4 = Large fix (1-2 weeks)
5 = Major refactor (1+ months)

Priority = Impact / Effort
Higher priority = fix first

Debt Tracking

## Technical Debt Backlog

| ID | Description | Impact | Effort | Priority | Status |
|----|-------------|--------|--------|----------|--------|
| TD-1 | God class OrderManager | 5 | 4 | 1.25 | Open |
| TD-2 | Duplicated tax calculation | 3 | 1 | 3.0 | Open |
| TD-3 | Missing unit tests | 4 | 3 | 1.33 | In Progress |
| TD-4 | Outdated Magento version | 5 | 5 | 1.0 | Open |

SonarQube Integration

# sonar-project.properties
sonar.projectKey=magento-store
sonar.sources=app/code/Vendor/
sonar.tests=dev/tests/
sonar.php.coverage.reportPath=coverage.xml
sonar.php.tests.reportPath=test-results.xml

# Metrics tracked:
# - Bugs
# - Vulnerabilities
# - Code Smells
# - Duplications
# - Coverage
# - Complexity

Key Takeaway

Quantify debt with metrics: duplication, complexity, coverage, errors. Score by impact/effort ratio. Track in backlog and use SonarQube for continuous monitoring.

Strangler Fig Pattern

// Old code
function processOrderLegacy($data) {
    // 500 lines of legacy code
}

// New code (strangler)
class OrderProcessor
{
    public function process(OrderRequest $request): Order
    {
        // New implementation
    }
}

// Migration: route some requests to new code
if ($this->shouldUseNew($request)) {
    return $this->orderProcessor->process($request);
} else {
    return processOrderLegacy($request);
}

Boy Scout Rule

// Leave code cleaner than you found it
// Before
function getData() {
    $data = $this->_loadData();
    return $data;
}

// After (cleaner)
public function getData(): array
{
    return $this->loadData();
}

Debt Paydown Schedule

## Sprint Debt Paydown

- 20% of sprint capacity for debt
- One debt item per sprint minimum
- Track debt velocity
- Review debt in sprint planning

## Debt Paydown Process

1. Identify highest priority debt
2. Create debt ticket
3. Estimate effort
4. Schedule in sprint
5. Refactor with tests
6. Verify no regression
7. Update documentation

Refactoring with Tests

// 1. Write tests for current behavior
public function testCalculateTax()
{
    $calculator = new TaxCalculator();
    $this->assertEquals(100, $calculator->calculate(1000));
}

// 2. Refactor
class TaxCalculator
{
    public function calculate(int $amount): int
    {
        return (int)($amount * $this->getTaxRate());
    }
    
    private function getTaxRate(): float
    {
        return $this->config->getTaxRate();
    }
}

// 3. Verify tests still pass
vendor/bin/phpunit --filter=TaxCalculator

Key Takeaway

Repay debt with strangler fig pattern, boy scout rule, and scheduled paydown. Always write tests before refactoring. Allocate sprint capacity for debt reduction.

Code Review Checklist

## Debt Prevention Checklist

- [ ] No code duplication
- [ ] Functions under 20 lines
- [ ] Classes under 200 lines
- [ ] Cyclomatic complexity < 10
- [ ] Unit tests included
- [ ] Documentation updated
- [ ] No deprecated APIs used
- [ ] No hardcoded values

Automated Quality Gates

# GitHub Actions quality gates
quality-gate:
  runs-on: ubuntu-latest
  steps:
    - name: PHPStan
      run: vendor/bin/phpstan analyse --level=6 app/code/Vendor/
    
    - name: PHPMD
      run: vendor/bin/phpmd app/code/Vendor/ text codesize,cleancode
    
    - name: Test Coverage
      run: vendor/bin/phpunit --coverage-text --min-coverage=80
    
    - name: Duplicate Code
      run: vendor/bin/phpcpd --min-lines=5 app/code/Vendor/

Definition of Done

## Definition of Done

- [ ] Code compiles without errors
- [ ] All tests pass
- [ ] Code review approved
- [ ] No new code smells
- [ ] Documentation updated
- [ ] No security vulnerabilities
- [ ] Performance benchmarks met

Dependency Management

# Regular dependency updates
composer update --dry-run

# Security audit
composer audit

# Update constraints
composer require magento/product-community-edition:2.4.6

# Lock file management
composer lock --no-update

Technical Debt Reviews

## Monthly Debt Review

1. Review debt metrics
2. Identify new debt items
3. Prioritize existing debt
4. Allocate capacity for paydown
5. Update debt backlog
6. Communicate to stakeholders

Key Takeaway

Prevent debt with code review checklists, automated quality gates, clear definition of done, and regular dependency updates. Conduct monthly debt reviews.