spacetris/REFACTORING_TODO.md

Tetris Refactoring TODO List

🚀 Phase 1: Foundation (Week 1-2) - CRITICAL ✅ COMPLETED

Core Architecture Setup

• Create ApplicationManager class

  • Design interface and basic structure
  • Implement initialize(), run(), shutdown() methods
  • Move SDL initialization from main() to ApplicationManager
  • Add proper error handling and cleanup
  • Test basic application lifecycle

• Extract RenderManager class

  • Create rendering abstraction layer
  • Move SDL_Window and SDL_Renderer management
  • Implement viewport and scaling logic
  • Add texture and primitive rendering methods
  • Test rendering pipeline isolation

• Implement basic StateManager improvements

  • Enhance current StateManager with stack support
  • Add state validation and error handling
  • Implement proper state lifecycle management
  • Test state transitions thoroughly

✅ MILESTONE ACHIEVED: Core architecture foundation is complete! We now have:

• Clean separation between main() and application logic
• Abstracted rendering system
• Enhanced state management with proper lifecycle
• Working refactored application (tetris_refactored.exe) alongside original
• Proper error handling and logging throughout

Immediate Code Cleanup ✅ COMPLETED

• Remove global variables from main.cpp

  • Move static variables to appropriate managers (GlobalState)
  • Remove global texture and font variables (AssetManager)
  • Eliminate global state flags (GlobalState singleton)
  • Clean up static function declarations

• Extract constants to configuration

  • Create Config namespace with all constants
  • Remove magic numbers from main.cpp
  • Define window size constants
  • Set up gameplay timing constants

🔧 Phase 2: Core Systems (Week 3-4) - HIGH PRIORITY ✅ COMPLETED

Input Management ✅ COMPLETED

• Create InputManager class

  • Implement keyboard state tracking
  • Add mouse input handling
  • Create event handler registration system
  • Implement DAS/ARR logic in InputManager
  • Test input responsiveness and accuracy

• Refactor event handling in main()

  • Move SDL event polling to InputManager
  • Replace inline event handlers with registered callbacks
  • Simplify main loop event processing
  • Test all input scenarios (keyboard, mouse, gamepad)

Asset Management ✅ COMPLETED

• Create AssetManager class

  • Design resource loading interface
  • Implement texture management
  • Add font loading and management
  • Create sound asset handling
  • Add resource cleanup and error handling

• Migrate existing asset loading

  • Move texture loading from main() to AssetManager
  • Convert font initialization to use AssetManager
  • Update StateContext to use AssetManager
  • Test asset loading and memory management

State System Enhancement

• Implement IGameState interface

  • Define clear state contract
  • Add update(), render(), handleEvent() methods
  • Implement proper state lifecycle
  • Add state type identification

• Create StateFactory pattern

  • Design state creation interface
  • Implement factory registration system
  • Add state parameter passing
  • Test dynamic state creation

🎨 Phase 3: Rendering Systems (Week 5-6) - MEDIUM PRIORITY

UI Rendering Separation

• Create UIRenderer class

  • Extract button rendering logic
  • Implement popup rendering system
  • Add progress bar rendering
  • Create menu rendering components
  • Test UI rendering consistency

• Refactor state rendering

  • Update LoadingState to use UIRenderer
  • Modify MenuState rendering
  • Enhance LevelSelectorState visuals
  • Test all state rendering paths

Game Rendering Optimization

• Create GameRenderer class

  • Extract game board rendering
  • Implement piece rendering system
  • Add background management
  • Create HUD rendering components
  • Optimize rendering performance

• Enhance visual effects

  • Improve line clearing effects
  • Add piece drop animations
  • Enhance particle systems
  • Implement screen transitions

Background System

• Create BackgroundManager class
  • Implement level-based backgrounds
  • Add background caching system
  • Create smooth transitions
  • Test background loading performance

⚙️ Phase 4: Configuration (Week 7) - MEDIUM PRIORITY

Configuration System

• Implement ConfigManager class

  • Design configuration storage
  • Add file loading/saving
  • Implement runtime configuration updates
  • Add configuration validation
  • Test configuration persistence

• Migrate constants

  • Move window size settings
  • Convert gameplay constants
  • Update UI layout values
  • Set up default configurations

Settings Management

• Create settings persistence
  • Save audio preferences
  • Store control mappings
  • Remember window settings
  • Test settings across restarts

📡 Phase 5: Event System (Week 8) - MEDIUM PRIORITY

Event Bus Implementation

• Create EventBus template class

  • Implement subscription system
  • Add event publishing mechanism
  • Create handler management
  • Test event delivery reliability

• Define Game Events

  • Create LevelUp event
  • Implement LineCleared event
  • Add GameOver event
  • Define PieceSpawned event
  • Test event system integration

Audio System Decoupling

• Convert audio callbacks to events
  • Replace sound callbacks with event handlers
  • Implement music management events
  • Add audio configuration events
  • Test audio system responsiveness

🔌 Phase 6: Dependency Injection (Week 9) - LOW PRIORITY

Service Container

• Implement ServiceContainer class

  • Design service registration
  • Add dependency resolution
  • Implement service lifecycle
  • Test service dependencies

• Migrate to dependency injection

  • Update manager constructors
  • Implement service interfaces
  • Add service configuration
  • Test dependency resolution

🧪 Phase 7: Testing & Quality (Week 10) - LOW PRIORITY

Unit Testing Setup

• Set up testing framework

  • Configure Google Test or Catch2
  • Create test project structure
  • Add basic test utilities
  • Set up automated test running

• Write core tests

  • Test ApplicationManager lifecycle
  • Validate StateManager transitions
  • Test InputManager functionality
  • Verify AssetManager operations
  • Test ConfigManager persistence

Integration Testing

• Create integration test suite
  • Test manager interactions
  • Validate state transitions
  • Test complete game scenarios
  • Run performance regression tests

Code Quality

• Add static analysis
  • Configure clang-tidy
  • Set up cppcheck
  • Add memory leak detection
  • Run code coverage analysis

🔧 Optimization Tasks - ONGOING

Performance Optimization

• Profile rendering performance

  • Identify rendering bottlenecks
  • Optimize texture usage
  • Improve draw call batching
  • Test frame rate consistency

• Memory optimization

  • Analyze memory usage patterns
  • Optimize asset loading
  • Implement memory pooling where needed
  • Test for memory leaks

Code Quality Improvements

• Documentation

  • Add comprehensive class documentation
  • Document API interfaces
  • Create usage examples
  • Write development guidelines

• Error Handling

  • Implement consistent error handling
  • Add logging system
  • Create error recovery mechanisms
  • Test error scenarios

Platform Compatibility

• Cross-platform testing
  • Test on Windows
  • Validate Linux compatibility
  • Check macOS support
  • Test different screen resolutions

📊 Progress Tracking

Metrics to Monitor

• Code Complexity: Reduce main() from 1,678 to <100 lines
• Test Coverage: Achieve >90% code coverage
• Build Time: Maintain fast compilation
• Performance: No regression in frame rate
• Memory Usage: Stable memory consumption

Milestones

• Milestone 1: Basic managers extracted and working
• Milestone 2: State system fully refactored
• Milestone 3: Rendering system modularized
• Milestone 4: Configuration system implemented
• Milestone 5: Event system integrated
• Milestone 6: All tests passing, full documentation

Success Criteria

• Main function reduced to application setup only
• All components unit testable
• Easy to add new features without modifying core code
• Clear separation of concerns throughout codebase
• Comprehensive documentation and examples

---

📝 Notes

• Priority levels: CRITICAL = Must complete, HIGH = Important for maintainability, MEDIUM = Quality improvements, LOW = Nice to have
• Estimated timeline: 10 weeks for complete refactoring
• Risk mitigation: Each phase should maintain working application
• Testing strategy: Test after each major change to ensure no regressions
• Documentation: Update as you go, don't leave it for the end