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.
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
|