364 lines
8.6 KiB
Markdown
364 lines
8.6 KiB
Markdown
# 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:**
|
|
```cpp
|
|
// 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:**
|
|
```cpp
|
|
// 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:**
|
|
```cpp
|
|
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:**
|
|
```cpp
|
|
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:**
|
|
```cpp
|
|
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:**
|
|
```yaml
|
|
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
|