You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
139 lines
3.8 KiB
139 lines
3.8 KiB
# 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
|
|
|