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.
119 lines
3.7 KiB
119 lines
3.7 KiB
# 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
|
|
|