forked from trent_larson/crowd-funder-for-time-pwa
a224aced85
- 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
120 lines
3.7 KiB
Plaintext
120 lines
3.7 KiB
Plaintext
# 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
|