eff7e339af
- Remove legacy rule files (documentation.mdc, general_development.mdc, etc.) - Implement new meta-rule system with core, app, and feature categories - Add meta-rule files for different workflows (bug diagnosis, feature planning, etc.) - Create organized directory structure: core/, app/, features/, database/, etc. - Add comprehensive README.md for rules documentation - Establish new rule architecture with always-on and workflow-specific rules This restructuring improves rule organization, enables better workflow management, and provides clearer separation of concerns for different development tasks.
140 lines
3.8 KiB
Plaintext
140 lines
3.8 KiB
Plaintext
# 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
|