Embedded Files
# Code Commenting with AI + a Specialist: Why Manual Annotation Is a Thing of the Past
## The Problem: Code Without Comments or With Dead Comments
Here's the reality of most codebases:
**Option 1: No comments.**
The code was written three years ago. The author is gone. What does `processV2Final()` do — no idea. Why it's done this way — no idea. What edge cases are handled — no idea. A new developer spends hours getting up to speed.
**Option 2: Comments are outdated.**
The comment says: "Returns a list of active users." The code was rewritten long ago and returns a dictionary with metadata. The comment lies. This is worse than having no comment at all — it's **misinformation**.
**Option 3: Comments are boilerplate.**
```python
# Increment the counter by 1
counter += 1
```
This is not a comment. This is noise. It carries no information. It takes up space and creates an illusion of documentation.
**Option 4: Comments describe "what" instead of "why."**
```python
# Sort the array
arr.sort()
```
Okay, I can see you're sorting. But **why**? For what purpose? What's the business rationale? What edge case? None of that is here.
In all four cases, the result is the same: **the code carries no context**. And every new person, every agent, every reviewer wastes time figuring out what's going on.
---
## Why Manual Annotation Doesn't Work
Commenting code by hand is **routine**. Pure, repetitive, boilerplate routine. And like any routine, it:
**1. Gets postponed.**
The developer wrote the code. The task is closed. Comment it? Later. In the next sprint. Never. Because commenting doesn't provide immediate value here and now. It provides value in a month, when a new person joins. But that moment is far away.
**2. Gets done superficially.**
When commenting does happen (usually before a review or at the team lead's request), it's done in a rush. Superficially. "Function does X." No context, no rationale, no edge cases.
**3. Becomes outdated instantly.**
The code changes. The comment doesn't get updated. Within a week, the comment lies. Within a month, it misleads. Nobody keeps comments up to date because it's not a priority.
**4. Doesn't scale.**
On a 100k-line codebase, manual commenting takes weeks. On a 1M-line codebase — months. It's physically unmanageable for a single person or even a team.
**5. Doesn't capture tacit knowledge.**
The most important comments describe **why**. Why this algorithm was chosen. Why this edge case is handled this way. Why you can't use a different approach. This knowledge lives in the developer's head, but they don't write it down because "it's obvious" or "no time."
---
## The Solution: AI Generates, Specialist Verifies
Commenting code is a **perfect task for AI**:
- It's formulaic (the comment format is known)
- It's repetitive (needed for every file, every function)
- It requires reading code (AI reads code and understands what it does)
- It doesn't require judgment (the comment describes what's there, not making decisions)
But AI doesn't know **tacit knowledge**. It doesn't know why this particular approach was chosen. It doesn't know the business context. It doesn't know the bug history that led to this code.
So the correct model is:
**AI generates comments.** Reads the code, understands the structure, describes what the function does, what parameters it takes, what it returns, what edge cases it handles.
**The specialist verifies and enriches.** Checks that the AI understood the code correctly. Adds tacit knowledge: why it's done this way, what business constraints exist, what historical reasons led to this.
**AI updates comments when code changes.** When the code changes, AI automatically updates the comments. The specialist verifies.
This isn't "AI comments code." This is a **tandem**: AI does the routine work, the specialist adds value.
---
## How to Properly Prompt AI for Comment Generation
### Bad prompt:
> "Comment this code"
Result: AI will write superficial "what"-level comments. No context. No rationale. Noise.
### Good prompt:
```
Comment the code in [filename]. Rules:
1. For each public function:
- What it does (1 sentence)
- Parameters: what it expects, what constraints apply
- Return value: what it returns, in what format
- Edge cases: what special cases it handles
- Side effects: what it changes beyond the return value
2. For private functions:
- Brief description (1 line)
- Why it exists (if not obvious)
3. For complex algorithms:
- Why this approach was chosen
- Time and space complexity
- Limitations
4. DO NOT write:
- Obvious things ("increment the counter by 1")
- Paraphrasing the code in words
- Comments that duplicate the function name
5. Format: [docstring / JSDoc / doxygen — depending on the language]
```
Result: AI writes structured, informative comments. No noise. Focused on "why" instead of "what."
### For large codebases:
```
Comment the [module_name] module. Context:
- This module handles [business function]
- Key constraints: [list]
- Historical decisions: [if any]
- Related modules: [list]
Rules: [same as above]
Additionally:
- If you see code that looks like a hack — flag it as TODO with an explanation of what's suspicious
- If you see an implicit dependency on another module — note it explicitly
```
---
## How the Specialist Verifies the Result
AI generated the comments. The specialist **doesn't read every single one**. That would be the same routine. The specialist performs **selective verification**:
### Step 1: Noise Check
The specialist scans comments for:
- Obvious statements ("increment the counter")
- Paraphrasing code in words
- Comments that carry no information
If the AI wrote noise — adjusts the prompt and regenerates.
### Step 2: Accuracy Check
The specialist picks 5–10 random functions and checks:
- Did the AI correctly understand what the function does?
- Are the parameters and return value described correctly?
- Did the AI make up things that aren't in the code?
If the AI hallucinates — adjusts the prompt, adds the constraint: "Only describe what you see in the code. Don't invent anything."
### Step 3: Adding Tacit Knowledge
This is **the most important part**. AI doesn't know:
- Why this particular algorithm was chosen
- What business constraints led to this code
- What bugs were fixed and why the code looks this way
- What architectural decisions were made
The specialist adds this. Not for every function. But for **critical spots** where context matters.
Example:
AI wrote:
```python
def calculate_discount(user: User, order: Order) -> float:
"""Calculates the discount for a user based on their order.
Parameters:
user: User object with loyalty level
order: Order object with total and product categories
Returns:
float: Discount percentage (0-30%)
"""
```
The specialist enriches:
```python
def calculate_discount(user: User, order: Order) -> float:
"""Calculates the discount for a user based on their order.
Parameters:
user: User object with loyalty level
order: Order object with total and product categories
Returns:
float: Discount percentage (0-30%)
Business context:
Maximum 30% due to margin constraints (see ADR-047).
For "electronics" categories, no discount applies due to
supplier agreements (ticket PROJ-2341).
History:
Originally the discount was fixed (10%), but in Q3 2024
we switched to dynamic due to user churn.
See commit abc1234.
"""
```
This is **value** that AI won't generate. This is the specialist's **judgment and domain expertise**.
### Step 4: Staleness Check
The specialist sets up a process: on every code change, AI automatically updates comments. The specialist periodically verifies that comments haven't gone stale.
This can be automated through CI:
- On a PR that modifies a function, a check runs: have the comments been updated?
- If not — the PR doesn't merge until comments are updated
---
## Scaling to Large Codebases
On a 10k-file codebase, manual commenting is impossible. With AI — it's possible. But you need a process.
### Strategy: Prioritization
You don't need to comment everything at once. Prioritization:
**Priority 1: Public APIs and interfaces**
This is what other developers and agents see. Comments here are critical.
**Priority 2: Complex algorithms and business logic**
This is what's incomprehensible without context. Comments here carry the most value.
**Priority 3: Hacks and technical debt**
This is what looks strange and needs explanation. Comments here prevent "fixing" things that shouldn't be fixed.
**Priority 4: Everything else**
Commented as needed. Not all at once.
### Process: Iterative
**Iteration 1 (1-2 days):**
- AI comments all public APIs and interfaces
- Specialist verifies, adds business context
**Iteration 2 (2-3 days):**
- AI comments complex business logic
- Specialist verifies, adds historical context
**Iteration 3 (1-2 days):**
- AI comments hacks and flags suspicious spots
- Specialist decides: is it a bug or a feature? Adds explanation.
**Iteration 4 (ongoing):**
- On every code change, AI updates comments
- Specialist verifies critical changes
### Tools
**For generation:**
- Claude Code / Codex with a commenting prompt
- A skill in the repository `ai-harness/skills/code-commenting/`
- MCP tool for running on specific files/modules
**For verification:**
- A context-free subagent: reads code + comment, checks consistency
- If the comment doesn't match the code — flag for the specialist
**For keeping up to date:**
- CI hook: on function change, checks whether the comment was updated
- Automatic AI commenting trigger on PR
---
## Why This Isn't "AI Replaces Developers"
Critical point: AI **doesn't replace** the developer in commenting. AI does the **routine work**:
- Reads code
- Describes the structure
- Formats to standard
- Updates on changes
The specialist delivers **value**:
- Adds business context
- Explains implicit decisions
- Notes historical reasons
- Verifies accuracy
This is a **tandem**, not a replacement. AI doesn't know why you chose bubble sort over quicksort. The specialist does. AI doesn't know this hack appeared because of a library bug three years ago. The specialist does.
---
## Success Metrics
How to tell if commenting is working:
**1. New developer onboarding time.**
- Before: 2-3 weeks to understand a module
- After: 3-5 days
**2. Agent onboarding time.**
- Before: agent spends 50k+ tokens understanding a module
- After: 10-15k tokens (comments provide context)
**3. Outdated comment percentage.**
- Before: 40-60% of comments don't match the code
- After: 5-10% (AI updates automatically)
**4. Percentage of functions with comments.**
- Before: 20-30% (only what was forced)
- After: 90-100% (AI comments everything)
**5. Number of "what does this function do?" questions.**
- Before: Constantly
- After: Rarely (the answer is in the comment)
---
## Practical Checklist
**Step 1: Write your commenting prompt**
- Format (docstring, JSDoc, doxygen)
- What to include (structure, parameters, edge cases, side effects)
- What NOT to include (obvious things, code paraphrasing)
- Project context (business function, constraints)
**Step 2: Save it as a skill in ai-harness**
- `ai-harness/skills/code-commenting/skill.md`
- Tests: give a subagent uncommented code, run the skill, check the result
**Step 3: Run on priority modules**
- Public APIs and interfaces
- Complex business logic
- Hacks and technical debt
**Step 4: Verify**
- Check for noise (obvious things)
- Check for accuracy (5-10 random functions)
- Add tacit knowledge (business context, history)
**Step 5: Set up automatic updates**
- CI hook: code change → update comments
- Periodic check: once a month — audit freshness
**Step 6: Scale**
- Comment other modules as needed
- Not all at once. Prioritize by value.
---
## Conclusion
Manual code commenting is a **thing of the past**. It's routine that gets postponed, done superficially, becomes outdated instantly, and doesn't scale.
AI + a specialist is the **correct model**:
- AI generates comments (routine)
- Specialist verifies and adds tacit knowledge (judgment)
- AI updates on changes (automation)
- Specialist checks critical spots (oversight)
This scales to codebases of any size. It stays up to date. It carries value, not noise.
Code commenting is not "a chore for reviews." It's **knowledge infrastructure** that allows both people and agents to quickly get up to speed on code. Without it, everyone spends hours understanding. With it — minutes.
And this is yet another example of how **routine goes to AI, while the specialist retains task-setting and result verification**. Not replacement. Tandem.
Page updated
Google Sites
Report abuse