Skip to content

REFACTORING_PLAN.md

Latest commit

 

History

History
255 lines (200 loc) · 8 KB

REFACTORING_PLAN.md

File metadata and controls

255 lines (200 loc) · 8 KB

Listeningway Codebase Refactoring Plan

Executive Summary

This document outlines a systematic plan to eliminate anti-patterns and inefficiencies in the Listeningway codebase. The analysis identified 8 major categories of anti-patterns that impact code maintainability, readability, and performance.

Identified Anti-Patterns

1. Verbose Naming Convention (High Impact, Low Effort)

Problem: Excessive "DEFAULT_LISTENINGWAY_" prefixes throughout constants

  • 42 constants with unnecessarily verbose names
  • Adds no semantic value, reduces readability
  • Increases maintenance burden

Examples:

// Current (verbose)
constexpr size_t DEFAULT_LISTENINGWAY_NUM_BANDS = 32;
constexpr float DEFAULT_LISTENINGWAY_FLUX_ALPHA = 0.1f;

// Proposed (clean)
constexpr size_t DEFAULT_NUM_BANDS = 32;
constexpr float DEFAULT_FLUX_ALPHA = 0.1f;

2. Code Duplication (Medium Impact, Medium Effort)

Problem: Repetitive patterns in settings initialization and management

  • Macro-based INI read/write patterns
  • Repetitive equalizer band handling
  • Duplicated audio provider enumeration logic

Examples:

  • Settings initialization: 40+ repetitive lines in LoadAllTunables()
  • Equalizer bands: Manual switch statements for 5 bands
  • Audio format detection: Hardcoded switch statements

3. Large Functions/Files (Medium Impact, High Effort)

Problem: overlay.cpp has too many responsibilities (771 lines)

  • Single file handles: UI rendering, settings management, provider switching, formatting
  • Multiple helper functions that could be grouped into classes
  • Poor separation of concerns

Functions to extract:

  • DrawFrequencyBands() -> FrequencyBandRenderer class
  • DrawVolumeSpatializationBeat() -> VolumeRenderer class
  • DrawBeatDetectionAlgorithm() -> BeatDetectionUI class

4. Magic Numbers and Hardcoded Values (Low Impact, Low Effort)

Problem: Various hardcoded values without clear documentation

  • Audio format constants (1, 2, 6, 8) without enum
  • UI spacing values (4.0f, 6.0f) scattered throughout
  • Color constants without named definitions

5. Repetitive Switch Statements (Medium Impact, Medium Effort)

Problem: Pattern matching that could be abstracted

  • Equalizer band selection (5 identical cases)
  • Audio format detection (5+ cases)
  • Provider type mapping

6. Resource Management Patterns (Medium Impact, Medium Effort)

Problem: Manual COM interface management in multiple providers

  • Repetitive RAII patterns across audio providers
  • Inconsistent error handling
  • Manual reference counting

7. Thread Safety Inconsistencies (High Impact, Medium Effort)

Problem: Multiple mutex patterns that could be consolidated

  • Settings mutex vs data mutex
  • Inconsistent locking strategies
  • Potential deadlock scenarios

8. Error Handling Inconsistencies (Medium Impact, Medium Effort)

Problem: Inconsistent error handling patterns across audio providers

  • Mix of exceptions, return codes, and logging
  • Inconsistent error recovery strategies
  • Missing error propagation in some paths

Refactoring Priority Matrix

Anti-Pattern Impact Effort Priority Estimated Time
Verbose Naming High Low 1 2 hours
Magic Numbers Low Low 2 1 hour
Thread Safety High Medium 3 4 hours
Code Duplication Medium Medium 4 6 hours
Switch Statements Medium Medium 5 3 hours
Error Handling Medium Medium 6 5 hours
Resource Management Medium Medium 7 4 hours
Large Functions Medium High 8 8 hours

Total Estimated Time: 33 hours

Phase 1: Quick Wins (Priority 1-2)

1.1 Fix Verbose Naming Convention

Files to modify:

  • src/core/constants.h - Remove "DEFAULT_LISTENINGWAY_" prefix
  • src/core/settings.h - Update references
  • src/core/settings.cpp - Update references

Benefits:

  • Immediate readability improvement
  • Reduces visual noise
  • Sets precedent for clean naming

1.2 Create Enums for Magic Numbers

New files to create:

  • src/core/audio_formats.h - Audio format enum
  • src/core/ui_constants.h - UI spacing constants

Benefits:

  • Type safety
  • Self-documenting code
  • Easier maintenance

Phase 2: Structural Improvements (Priority 3-5)

2.1 Consolidate Thread Safety

Files to modify:

  • src/core/settings.cpp - Unified locking strategy
  • src/audio/audio_analysis.cpp - Consistent mutex usage

Approach:

  • Create SettingsManager class with internal synchronization
  • Remove global mutexes
  • Use RAII lock guards consistently

2.2 Eliminate Code Duplication

New abstractions to create:

  • ConfigurationManager class for INI operations
  • EqualizerBandArray class for band management
  • Template-based settings serialization

2.3 Replace Switch Statements with Polymorphism

New patterns to implement:

  • Audio format registry pattern
  • Equalizer band strategy pattern
  • Provider factory pattern

Phase 3: Architectural Refactoring (Priority 6-8)

3.1 Standardize Error Handling

New components:

  • Result<T, Error> type for consistent error handling
  • Centralized error logging strategy
  • Error recovery protocols

3.2 Improve Resource Management

New patterns:

  • RAII wrappers for COM interfaces
  • Smart pointer usage for audio resources
  • Automatic cleanup patterns

3.3 Break Down Large Functions

New classes to extract:

  • OverlayRenderer - Main overlay coordination
  • FrequencyBandRenderer - Frequency visualization
  • VolumeRenderer - Volume/spatialization display
  • SettingsUI - Settings management UI
  • BeatDetectionUI - Beat detection controls

Implementation Strategy

Step 1: Create Feature Branch

git checkout -b refactor/eliminate-anti-patterns

Step 2: Implement Phase 1 (Quick Wins)

  • Start with verbose naming fixes
  • Add magic number enums
  • Test after each change

Step 3: Implement Phase 2 (Structural)

  • One anti-pattern at a time
  • Maintain backward compatibility
  • Add unit tests for new components

Step 4: Implement Phase 3 (Architectural)

  • Break down into smaller sub-branches
  • Extensive testing required
  • Performance benchmarking

Success Metrics

Code Quality Metrics

  • Lines of code reduction: Target 15-20%
  • Cyclomatic complexity reduction: Target 30%
  • Code duplication elimination: Target 80%

Maintainability Metrics

  • Reduced build times
  • Easier onboarding for new developers
  • Fewer bug reports related to anti-patterns

Performance Metrics

  • No performance regression
  • Improved memory usage patterns
  • Better thread contention characteristics

Risk Assessment

Low Risk

  • Verbose naming changes
  • Magic number enumeration
  • Adding new abstractions alongside existing code

Medium Risk

  • Thread safety consolidation
  • Large function breakdown
  • Error handling standardization

High Risk

  • Resource management changes
  • Core audio processing modifications

Testing Strategy

Unit Tests

  • Create tests for new abstractions
  • Regression tests for modified components
  • Performance tests for critical paths

Integration Tests

  • Audio provider switching
  • Settings persistence
  • UI functionality

Manual Testing

  • Real-world audio scenarios
  • Different audio formats
  • Provider switching under load

Rollback Plan

  • Each phase implemented in separate commits
  • Feature flags for new implementations
  • Ability to revert to previous patterns if issues arise
  • Comprehensive backup of current working state

Next Steps

  1. Approval - Review and approve this refactoring plan
  2. Environment Setup - Create feature branch and testing environment
  3. Phase 1 Implementation - Start with verbose naming fixes
  4. Iterative Development - Implement one anti-pattern fix at a time
  5. Testing and Validation - Comprehensive testing after each phase
  6. Documentation - Update code documentation and architecture diagrams
  7. Team Training - Share new patterns and best practices

Document Version: 1.0
Last Updated: June 4, 2025
Next Review: After Phase 1 completion