
# TinyTorch Module Development Best Practices

## Core Principles

### Real Data, Real Systems
- **Use production datasets**: Students work with CIFAR-10, ImageNet, etc. - never mock/fake data
- **Show progress feedback**: Downloads, training need visual progress indicators
- **Cache for efficiency**: Download once, use repeatedly
- **Real-world scale**: Use actual dataset sizes, not toy examples
- **Systems thinking**: Consider performance, memory, caching, user experience

### Educational Excellence
- **"Build → Use → Understand → Repeat"**: Follow this cycle religiously
- **Progressive complexity**: Easy → Medium → Hard with clear difficulty indicators
- **Comprehensive guidance**: TODO sections with approach, examples, hints, systems thinking
- **Real-world connections**: Connect every concept to production ML engineering

## Student Implementation Structure

```python
def student_method(self, params):
    """
    TODO: Clear, specific task description
    
    APPROACH:
    1. Concrete first step with specific guidance
    2. Concrete second step with specific guidance
    3. Concrete third step with specific guidance
    
    EXAMPLE:
    Input: actual_data_example
    Expected: concrete_expected_output
    
    HINTS:
    - Helpful guidance without giving code
    - Systems thinking consideration
    - Real-world connection
    
    SYSTEMS THINKING:
    - Performance consideration
    - Scalability question
    - User experience aspect
    """
    raise NotImplementedError("Student implementation required")
```

## Progress Feedback Pattern

```python
def _download_progress_hook(self, count, block_size, total_size):
    """Progress callback for downloads."""
    if total_size > 0:
        percent = min(100, (count * block_size * 100) // total_size)
        mb_downloaded = (count * block_size) / (1024 * 1024)
        mb_total = total_size / (1024 * 1024)
        
        # Visual progress bar
        bar_length = 50
        filled_length = int(bar_length * percent // 100)
        bar = '█' * filled_length + '░' * (bar_length - filled_length)
        
        print(f'\r📥 [{bar}] {percent}% ({mb_downloaded:.1f}/{mb_total:.1f} MB)', 
              end='', flush=True)
```

## Visual Feedback Pattern (Development Only)

```python
def show_data_samples(dataset, num_samples=8):
    """Show grid of actual data samples (development only)."""
    # NOT exported to package - development feedback only
    if not _should_show_plots():
        return
        
    fig, axes = plt.subplots(2, 4, figsize=(12, 6))
    for i in range(num_samples):
        image, label = dataset[i]
        # Show actual data with proper visualization
        axes[i//4, i%4].imshow(image.transpose(1, 2, 0))
        axes[i//4, i%4].set_title(f'Class: {label}')
    plt.show()
```

## Key Anti-Patterns to Avoid

### ❌ Don't Use Mock Data
```python
# BAD: Synthetic/mock data
class MockDataset:
    def __init__(self, size):
        self.data = np.random.randn(size, 784)  # Fake data
        
# GOOD: Real data
class CIFAR10Dataset:
    def __init__(self, root, train=True, download=True):
        self._download_if_needed()  # Real CIFAR-10 data
```

### ❌ Don't Skip Progress Feedback
```python
# BAD: Silent long operations
def download_data():
    urllib.request.urlretrieve(url, filename)  # No feedback
    
# GOOD: Progress feedback
def download_data():
    urllib.request.urlretrieve(url, filename, reporthook=self._progress_hook)
```

### ❌ Don't Export Visual Functions
```python
# BAD: Visual functions in package exports
#| export
def show_images(data):
    plt.imshow(data)  # Creates matplotlib dependency in package
    
# GOOD: Development-only visual functions
def show_images(data):
    if not _should_show_plots():
        return
    plt.imshow(data)  # Not exported, development only
```

## Quality Standards

### Before Release Checklist
- [ ] Uses real data, not synthetic/mock data
- [ ] Includes progress feedback for long operations
- [ ] Visual feedback functions (development only, not exported)
- [ ] TODO guidance includes systems thinking
- [ ] Clean separation between development and exports
- [ ] Follows "Build → Use → Understand → Repeat" progression

### Student Experience Requirements
- [ ] Clear learning progression
- [ ] Immediate feedback and validation
- [ ] Real-world relevance and connections
- [ ] Motivating and engaging content
- [ ] Smooth transition to next modules

## Success Metrics

**Students should be able to:**
- Explain what they built in simple terms
- Modify code to solve related problems
- Connect module concepts to real ML systems
- Debug issues by understanding the system

**Modules should achieve:**
- High student engagement and completion rates
- Smooth progression to next modules
- Real-world relevance and production quality
- Consistent patterns across the curriculum

---

**Remember**: We're teaching ML systems engineering, not just algorithms. Every module should reflect real-world practices and challenges while maintaining the "Build → Use → Understand" educational cycle.
