spacetris/IMPROVEMENTS_CHECKLIST.md

Tetris SDL3 - Improvements Checklist

Quick reference for implementing the recommendations from CODE_ANALYSIS.md

---

🔴 High Priority (Critical)

1. Smart Pointer Wrapper for SDL Resources

Status: ❌ Not Started
Effort: 2-3 hours
Impact: Prevents memory leaks, improves safety

Action Items:

• Create src/utils/SDLPointers.h with smart pointer wrappers
• Replace raw SDL_Texture* in MenuState.h (lines 17-21)
• Replace raw SDL_Texture* in PlayingState.h
• Update main.cpp texture loading
• Test all states to ensure no regressions

Code Template:

// src/utils/SDLPointers.h
#pragma once
#include <SDL3/SDL.h>
#include <memory>

struct SDL_TextureDeleter {
    void operator()(SDL_Texture* tex) const {
        if (tex) SDL_DestroyTexture(tex);
    }
};

struct SDL_SurfaceDeleter {
    void operator()(SDL_Surface* surf) const {
        if (surf) SDL_DestroySurface(surf);
    }
};

using SDL_TexturePtr = std::unique_ptr<SDL_Texture, SDL_TextureDeleter>;
using SDL_SurfacePtr = std::unique_ptr<SDL_Surface, SDL_SurfaceDeleter>;

---

2. Remove Debug File I/O

Status: ❌ Not Started
Effort: 30 minutes
Impact: Performance, code cleanliness

Action Items:

• Remove or wrap fopen("tetris_trace.log") calls in MenuState.cpp
• Remove or wrap similar calls in other files
• Replace with SDL_LogTrace or conditional compilation
• Delete tetris_trace.log from repository

Files to Update:

• src/states/MenuState.cpp (lines 182-184, 195-203, 277-278, 335-337)
• src/main.cpp (if any similar patterns exist)

Replacement Pattern:

// Before:
FILE* f = fopen("tetris_trace.log", "a");
if (f) { fprintf(f, "MenuState::render entry\n"); fclose(f); }

// After:
SDL_LogTrace(SDL_LOG_CATEGORY_APPLICATION, "MenuState::render entry");

---

3. Improve Error Handling in Asset Loading

Status: ❌ Not Started
Effort: 2 hours
Impact: Better debugging, prevents crashes

Action Items:

• Update loadTextureFromImage to return error information
• Add validation for all asset loads in main.cpp
• Create fallback assets for missing resources
• Add startup asset validation

Example:

struct AssetLoadResult {
    SDL_TexturePtr texture;
    std::string error;
    bool success;
};

AssetLoadResult loadTextureFromImage(SDL_Renderer* renderer, 
                                     const std::string& path);

---

🟡 Medium Priority (Important)

4. Extract Common Patterns

Status: ❌ Not Started
Effort: 3-4 hours
Impact: Reduces code duplication

Action Items:

• Create ExitPopupHelper class in StateContext.h
• Update MenuState.cpp to use helper
• Update PlayingState.cpp to use helper
• Update OptionsState.cpp to use helper

---

5. Move Magic Numbers to Config.h

Status: ❌ Not Started
Effort: 1 hour
Impact: Maintainability

Action Items:

• Add menu button constants to Config::UI
• Add rendering constants to appropriate namespace
• Update MenuState.cpp to use config constants
• Update UIRenderer.cpp to use config constants

Constants to Add:

namespace Config::UI {
    constexpr float MENU_BUTTON_WIDTH = 200.0f;
    constexpr float MENU_BUTTON_HEIGHT = 70.0f;
    constexpr float MENU_BUTTON_Y_FRACTION = 0.865f;
    constexpr float MENU_BUTTON_SPACING = 210.0f;
}

---

6. Add Unit Tests

Status: ⚠️ Minimal (only GravityTests)
Effort: 8-10 hours
Impact: Code quality, regression prevention

Action Items:

• Create tests/GameLogicTests.cpp
  • Test piece spawning
  • Test rotation
  • Test collision detection
  • Test line clearing
  • Test scoring
• Create tests/ScoreManagerTests.cpp
  • Test score submission
  • Test high score detection
  • Test persistence
• Create tests/StateTransitionTests.cpp
  • Test state transitions
  • Test state lifecycle (onEnter/onExit)
• Update CMakeLists.txt to include new tests

---

🟢 Low Priority (Nice to Have)

7. Add Doxygen Documentation

Status: ❌ Not Started
Effort: 4-6 hours
Impact: Developer onboarding

Action Items:

• Create Doxyfile configuration
• Add class-level documentation to core classes
• Add function-level documentation to public APIs
• Generate HTML documentation
• Add to build process

---

8. Performance Profiling

Status: ❌ Not Started
Effort: 4-6 hours
Impact: Depends on findings

Action Items:

• Profile with Visual Studio Profiler / Instruments
• Identify hotspots
• Optimize critical paths
• Add performance benchmarks

---

9. Standardize Member Variable Naming

Status: ⚠️ Inconsistent
Effort: 2-3 hours
Impact: Code consistency

Action Items:

• Decide on naming convention (recommend m_ prefix for private members)
• Update all class member variables
• Update documentation to reflect convention

Convention Recommendation:

class Example {
public:
    int publicValue;  // No prefix for public members
    
private:
    int m_privateValue;      // m_ prefix for private members
    float m_memberVariable;  // Consistent across all classes
};

---

📋 Code Quality Improvements

10. Add .clang-format

Status: ❌ Not Started
Effort: 15 minutes
Impact: Consistent formatting

Action Items:

• Create .clang-format file in project root
• Run formatter on all source files
• Add format check to CI/CD

Suggested .clang-format:

BasedOnStyle: LLVM
IndentWidth: 4
ColumnLimit: 120
PointerAlignment: Left
AllowShortFunctionsOnASingleLine: Empty

---

11. Add README.md

Status: ❌ Missing
Effort: 1 hour
Impact: Project documentation

Action Items:

• Create README.md with:
  • Project description
  • Screenshots/GIF
  • Build instructions
  • Dependencies
  • Controls
  • License

---

12. Set Up CI/CD

Status: ❌ Not Started
Effort: 2-3 hours
Impact: Automated testing

Action Items:

• Create .github/workflows/build.yml
• Add Windows build job
• Add macOS build job
• Add test execution
• Add artifact upload

---

🔧 Refactoring Opportunities

13. Create Asset Manager

Status: ❌ Not Started
Effort: 4-5 hours
Impact: Better resource management

Action Items:

• Create src/core/assets/AssetManager.h
• Implement texture caching
• Implement font caching
• Update states to use AssetManager
• Add asset preloading

---

14. Implement Event System

Status: ❌ Not Started
Effort: 6-8 hours
Impact: Decoupling, flexibility

Action Items:

• Create src/core/events/EventBus.h
• Define event types
• Replace callbacks with events
• Update Game class to publish events
• Update Audio system to subscribe to events

---

15. Component-Based UI

Status: ❌ Not Started
Effort: 8-10 hours
Impact: UI maintainability

Action Items:

• Create src/ui/components/Button.h
• Create src/ui/components/Panel.h
• Create src/ui/components/Label.h
• Refactor MenuState to use components
• Refactor OptionsState to use components

---

📊 Progress Tracking

Category	Total Items	Completed	In Progress	Not Started
High Priority	3	0	0	3
Medium Priority	3	0	0	3
Low Priority	3	0	0	3
Code Quality	3	0	0	3
Refactoring	3	0	0	3
TOTAL	15	0	0	15

---

🎯 Suggested Implementation Order

Week 1: Critical Fixes

1. Remove debug file I/O (30 min)
2. Smart pointer wrapper (2-3 hours)
3. Improve error handling (2 hours)

Week 2: Code Quality

4. Move magic numbers to Config.h (1 hour)
5. Extract common patterns (3-4 hours)
6. Add .clang-format (15 min)
7. Add README.md (1 hour)

Week 3: Testing

8. Add GameLogicTests (4 hours)
9. Add ScoreManagerTests (2 hours)
10. Add StateTransitionTests (2 hours)

Week 4: Documentation & CI

11. Set up CI/CD (2-3 hours)
12. Add Doxygen documentation (4-6 hours)

Future Iterations:

13. Performance profiling
14. Asset Manager
15. Event System
16. Component-Based UI

---

📝 Notes

• Mark items as completed by changing ❌ to ✅
• Update progress table as you complete items
• Feel free to reorder based on your priorities
• Some items can be done in parallel
• Consider creating GitHub issues for tracking

---

Last Updated: 2025-12-03
Next Review: After completing High Priority items