forked from trent_larson/crowd-funder-for-time-pwa
refactor(cursor-rules): restructure rules architecture with meta-rule system
- Reorganize cursor rules into logical domain-based directories - Implement meta-rule system for workflow-specific rule bundling - Move core rules to dedicated /core directory - Consolidate development rules under /development namespace - Add architectural patterns and implementation examples - Create workflow-specific meta-rules for common development tasks - Remove deprecated standalone rule files - Update package dependencies for new rule structure BREAKING CHANGE: Cursor rules file structure has been reorganized Files moved from root rules directory to domain-specific subdirectories
This commit is contained in:
119
.cursor/rules/development/historical_comment_management.mdc
Normal file
119
.cursor/rules/development/historical_comment_management.mdc
Normal file
@@ -0,0 +1,119 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user