# Historical Comment Management — Code Clarity Guidelines

> **Agent role**: When encountering historical comments about removed
> methods, deprecated patterns, or architectural changes, apply these
> guidelines to maintain code clarity and developer guidance.

## Overview

Historical comments should either be **removed entirely** or **transformed
into actionable guidance** for future developers. Avoid keeping comments
that merely state what was removed without explaining why or what to do
instead.

## Decision Framework

### When to Remove Comments

- **Obsolete Information**: Comment describes functionality that no
  longer exists
- **Outdated Context**: Comment refers to old patterns that are no
  longer relevant
- **No Actionable Value**: Comment doesn't help future developers
  make decisions

### When to Transform Comments

- **Migration Guidance**: Future developers might need to understand
  the evolution
- **Alternative Approaches**: The comment can guide future
  implementation choices
- **Historical Context**: Understanding the change helps with
  current decisions

## Transformation Patterns

### 1. **Removed Method** → **Alternative Approach**

```typescript
// Before: Historical comment
// turnOffNotifyingFlags method removed - notification state is now
// managed by NotificationSection component

// After: Actionable guidance
// Note: Notification state management has been migrated to
// NotificationSection component
```

### 2. **Deprecated Pattern** → **Current Best Practice**

```typescript
// Before: Historical comment
// Database access has been migrated from direct IndexedDB calls to
// PlatformServiceMixin

// After: Actionable guidance
// This provides better platform abstraction and consistent error
// handling across web/mobile/desktop

// When adding new database operations, use this.$getContact(),
// this.$saveSettings(), etc.
```

## Best Practices

### 1. **Use Actionable Language**: Guide future decisions, not just

document history

### 2. **Provide Alternatives**: Always suggest what to use instead

### 3. **Update Related Docs**: If removing from code, consider

adding to documentation

### 4. **Keep Context**: Include enough information to understand

why the change was made

## Integration Points

- Apply these rules when reviewing code changes
- Use during code cleanup and refactoring
- Include in code review checklists

---

**See also**:

- `.cursor/rules/development/historical_comment_patterns.mdc` for detailed
  transformation examples and patterns

**Status**: Active comment management guidelines
**Priority**: Medium
**Estimated Effort**: Ongoing reference
**Dependencies**: None
**Stakeholders**: Development team, Code reviewers

## Model Implementation Checklist

### Before Comment Review

- [ ] **Code Analysis**: Review code for historical or outdated comments
- [ ] **Context Understanding**: Understand the current state of the codebase
- [ ] **Pattern Identification**: Identify comments that need transformation or removal
- [ ] **Documentation Planning**: Plan where to move important historical context

### During Comment Management

- [ ] **Transformation**: Convert historical comments to actionable guidance
- [ ] **Alternative Provision**: Suggest current best practices and alternatives
- [ ] **Context Preservation**: Maintain enough information to understand changes
- [ ] **Documentation Update**: Move important context to appropriate documentation

### After Comment Management

- [ ] **Code Review**: Ensure transformed comments provide actionable value
- [ ] **Documentation Sync**: Verify related documentation is updated
- [ ] **Team Communication**: Share comment transformation patterns with team
- [ ] **Process Integration**: Include comment management in code review checklists