# Historical Comment Patterns — Transformation Examples

> **Agent role**: Reference this file for specific patterns and
  examples when transforming historical comments into actionable guidance.

## 🔄 Transformation Patterns

### 1. From Removal Notice to Migration Note

```typescript

// ❌ REMOVE THIS
// turnOffNotifyingFlags method removed - 
  notification state is now managed by NotificationSection component

// ✅ TRANSFORM TO THIS
// Note: Notification state management has been migrated to NotificationSection
  component
// which handles its own lifecycle and persistence via PlatformServiceMixin

```

### 2. From Deprecation Notice to Implementation Guide

```typescript

// ❌ REMOVE THIS
// This will be handled by the NewComponent now
// No need to call oldMethod() as it's no longer needed

// ✅ TRANSFORM TO THIS
// Note: This functionality has been migrated to NewComponent
// which provides better separation of concerns and testability

```

### 3. From Historical Note to Architectural Context

```typescript

// ❌ REMOVE THIS
// Old approach: used direct database calls
// New approach: uses service layer

// ✅ TRANSFORM TO THIS
// Note: Database access has been abstracted through service layer
// for better testability and platform independence

```

## 🚫 Anti-Patterns to Remove

- Comments that only state what was removed

- Comments that don't explain the current approach

- Comments that reference non-existent methods

- Comments that are self-evident from the code

- Comments that don't help future decision-making

## 📚 Examples

### Good Historical Comment (Keep & Transform)

```typescript

// Note: Database access has been migrated from direct IndexedDB calls to
  PlatformServiceMixin
// This provides better platform abstraction and 
  consistent error handling across web/mobile/desktop
// When adding new database operations, use this.$getContact(),
  this.$saveSettings(), etc.

```

### Bad Historical Comment (Remove)

```typescript

// Old method getContactFromDB() removed - now handled by PlatformServiceMixin
// No need to call the old method anymore

```

## 🎯 When to Use Each Pattern

### Migration Notes

- Use when functionality has moved to a different component/service

- Explain the new location and why it's better

- Provide guidance on how to use the new approach

### Implementation Guides

- Use when patterns have changed significantly

- Explain the architectural benefits

- Show how to implement the new pattern

### Architectural Context

- Use when the change represents a system-wide improvement

- Explain the reasoning behind the change

- Help future developers understand the evolution

---

**See also**: `.cursor/rules/development/historical_comment_management.mdc` for
  the core decision framework and best practices.

## Model Implementation Checklist

### Before Comment Review

- [ ] **Code Analysis**: Review code for historical or outdated comments
- [ ] **Pattern Identification**: Identify comments that need transformation or removal
- [ ] **Context Understanding**: Understand the current state of the codebase
- [ ] **Transformation Planning**: Plan how to transform or remove comments

### During Comment Transformation

- [ ] **Pattern Selection**: Choose appropriate transformation pattern
- [ ] **Content Creation**: Create actionable guidance for future developers
- [ ] **Alternative Provision**: Suggest current best practices and approaches
- [ ] **Context Preservation**: Maintain enough information to understand changes

### After Comment Transformation

- [ ] **Code Review**: Ensure transformed comments provide actionable value
- [ ] **Pattern Documentation**: Document transformation patterns for team use
- [ ] **Team Communication**: Share comment transformation patterns with team
- [ ] **Process Integration**: Include comment patterns in code review checklists