9f00797925
All checks were successful
Deploy to Staging / Build Images (push) Successful in 23s
Deploy to Staging / Deploy to Staging (push) Successful in 36s
Deploy to Staging / Verify Staging (push) Successful in 6s
Deploy to Staging / Notify Staging Ready (push) Successful in 6s
Deploy to Staging / Notify Staging Failure (push) Has been skipped
136 lines
6.7 KiB
Markdown
136 lines
6.7 KiB
Markdown
# Temporal Contamination in Code Comments
|
|
|
|
This document defines terminology for identifying comments that leak information
|
|
about code history, change processes, or planning artifacts. Both
|
|
@agent-technical-writer and @agent-quality-reviewer reference this
|
|
specification.
|
|
|
|
## The Core Principle
|
|
|
|
> **Timeless Present Rule**: Comments must be written from the perspective of a
|
|
> reader encountering the code for the first time, with no knowledge of what
|
|
> came before or how it got here. The code simply _is_.
|
|
|
|
**Why this matters**: Change-narrative comments are an LLM artifact -- a
|
|
category error, not merely a style issue. The change process is ephemeral and
|
|
irrelevant to the code's ongoing existence. Humans writing comments naturally
|
|
describe what code IS, not what they DID to create it. Referencing the change
|
|
that created a comment is fundamentally confused about what belongs in
|
|
documentation.
|
|
|
|
Think of it this way: a novel's narrator never describes the author's typing
|
|
process. Similarly, code comments should never describe the developer's editing
|
|
process. The code simply exists; the path to its existence is invisible.
|
|
|
|
In a plan, this means comments are written _as if the plan was already
|
|
executed_.
|
|
|
|
## Detection Heuristic
|
|
|
|
Evaluate each comment against these five questions. Signal words are examples --
|
|
extrapolate to semantically similar constructs.
|
|
|
|
### 1. Does it describe an action taken rather than what exists?
|
|
|
|
**Category**: Change-relative
|
|
|
|
| Contaminated | Timeless Present |
|
|
| -------------------------------------- | ----------------------------------------------------------- |
|
|
| `// Added mutex to fix race condition` | `// Mutex serializes cache access from concurrent requests` |
|
|
| `// New validation for the edge case` | `// Rejects negative values (downstream assumes unsigned)` |
|
|
| `// Changed to use batch API` | `// Batch API reduces round-trips from N to 1` |
|
|
|
|
Signal words (non-exhaustive): "Added", "Replaced", "Now uses", "Changed to",
|
|
"New", "Updated", "Refactored"
|
|
|
|
### 2. Does it compare to something not in the code?
|
|
|
|
**Category**: Baseline reference
|
|
|
|
| Contaminated | Timeless Present |
|
|
| ------------------------------------------------- | ------------------------------------------------------------------- |
|
|
| `// Replaces per-tag logging with summary` | `// Single summary line; per-tag logging would produce 1500+ lines` |
|
|
| `// Unlike the old approach, this is thread-safe` | `// Thread-safe: each goroutine gets independent state` |
|
|
| `// Previously handled in caller` | `// Encapsulated here; caller should not manage lifecycle` |
|
|
|
|
Signal words (non-exhaustive): "Instead of", "Rather than", "Previously",
|
|
"Replaces", "Unlike the old", "No longer"
|
|
|
|
### 3. Does it describe where to put code rather than what code does?
|
|
|
|
**Category**: Location directive
|
|
|
|
| Contaminated | Timeless Present |
|
|
| ----------------------------- | --------------------------------------------- |
|
|
| `// After the SendAsync call` | _(delete -- diff structure encodes location)_ |
|
|
| `// Insert before validation` | _(delete -- diff structure encodes location)_ |
|
|
| `// Add this at line 425` | _(delete -- diff structure encodes location)_ |
|
|
|
|
Signal words (non-exhaustive): "After", "Before", "Insert", "At line", "Here:",
|
|
"Below", "Above"
|
|
|
|
**Action**: Always delete. Location is encoded in diff structure, not comments.
|
|
|
|
### 4. Does it describe intent rather than behavior?
|
|
|
|
**Category**: Planning artifact
|
|
|
|
| Contaminated | Timeless Present |
|
|
| -------------------------------------- | -------------------------------------------------------- |
|
|
| `// TODO: add retry logic later` | _(delete, or implement retry now)_ |
|
|
| `// Will be extended for batch mode` | _(delete -- do not document hypothetical futures)_ |
|
|
| `// Temporary workaround until API v2` | `// API v1 lacks filtering; client-side filter required` |
|
|
|
|
Signal words (non-exhaustive): "Will", "TODO", "Planned", "Eventually", "For
|
|
future", "Temporary", "Workaround until"
|
|
|
|
**Action**: Delete, implement the feature, or reframe as current constraint.
|
|
|
|
### 5. Does it describe the author's choice rather than code behavior?
|
|
|
|
**Category**: Intent leakage
|
|
|
|
| Contaminated | Timeless Present |
|
|
| ------------------------------------------ | ---------------------------------------------------- |
|
|
| `// Intentionally placed after validation` | `// Runs after validation completes` |
|
|
| `// Deliberately using mutex over channel` | `// Mutex serializes access (single-writer pattern)` |
|
|
| `// Chose polling for reliability` | `// Polling: 30% webhook delivery failures observed` |
|
|
| `// We decided to cache at this layer` | `// Cache here: reduces DB round-trips for hot path` |
|
|
|
|
Signal words (non-exhaustive): "intentionally", "deliberately", "chose",
|
|
"decided", "on purpose", "by design", "we opted"
|
|
|
|
**Action**: Extract the technical justification; discard the decision narrative.
|
|
The reader doesn't need to know someone "decided" -- they need to know WHY this
|
|
approach works.
|
|
|
|
**The test**: Can you delete the intent word and the comment still makes sense?
|
|
If yes, delete the intent word. If no, reframe around the technical reason.
|
|
|
|
---
|
|
|
|
**Catch-all**: If a comment only makes sense to someone who knows the code's
|
|
history, it is temporally contaminated -- even if it does not match any category
|
|
above.
|
|
|
|
## Subtle Cases
|
|
|
|
Same word, different verdict -- demonstrates that detection requires semantic
|
|
judgment, not keyword matching.
|
|
|
|
| Comment | Verdict | Reasoning |
|
|
| -------------------------------------- | ------------ | ------------------------------------------------ |
|
|
| `// Now handles edge cases properly` | Contaminated | "properly" implies it was improper before |
|
|
| `// Now blocks until connection ready` | Clean | "now" describes runtime moment, not code history |
|
|
| `// Fixed the null pointer issue` | Contaminated | Describes a fix, not behavior |
|
|
| `// Returns null when key not found` | Clean | Describes behavior |
|
|
|
|
## The Transformation Pattern
|
|
|
|
> **Extract the technical justification, discard the change narrative.**
|
|
|
|
1. What useful info is buried? (problem, behavior)
|
|
2. Reframe as timeless present
|
|
|
|
Example: "Added mutex to fix race" -> "Mutex serializes concurrent access"
|