Code Clarity And Docs

---
name: code-clarity-and-docs
description: "Audits and improves code clarity and documentation using APOSD's obviousness rules: naming quality, comment accuracy, AI-facing doc completeness, and the comments-first workflow for new code. Not for generating project-wide convention docs (use code-standards) or structural simplification of the code itself (use aposd-simplifying-complexity)."
user-invocable: false
---

# Code Clarity and Documentation

## The Obviousness Rule

**If a code reviewer says your code is not obvious, it is not obvious** -- regardless of how clear it seems to you.

**For new code:** Write comments BEFORE implementation. If the comment is hard to write, fix the design, not the comment.

---

## Comments-First Workflow

For new classes/methods, write comments BEFORE implementation:

```
1. Write class interface comment (what abstraction it provides)
2. Write interface comments for public methods (signatures + comments, empty bodies)
3. Iterate on comments until structure feels right
4. Write instance variable declarations with comments
5. Fill in method bodies, adding implementation comments as needed
6. New methods discovered during implementation: comment before body
7. New variables: comment at same time as declaration
```

**Applies to:** writing from scratch, copy-paste-modify, extending functions (>5 lines), interface-changing refactors, prototype-to-production, test methods, non-trivial lambdas.

**Exempt:** one-liner utilities with precise names, trivial getters/setters, character-level bug fixes, temp debug code (mark `// TEMP:`).

---

## Comment Types and When to Use Them

| Type | Where | Purpose |
|------|-------|---------|
| **Interface** | Declarations | Define abstraction, usage info -- required for every public entity |
| **Implementation** | Inside methods | Help understand what code does -- optional for simple methods |
| **Cross-Module** | Dependencies | Describe cross-boundary relationships |

### Interface vs Implementation Comments

| Interface Comment | Implementation Comment |
|-------------------|------------------------|
| Describes externally visible behavior | Describes internal workings |
| Defines the abstraction | Helps understand how code works |
| What user needs to use it | What maintainer needs to modify it |
| **Never include implementation details** | Can reference interface concepts |

---

## The "Different Words" Test

**If your comment restates the code, it adds zero value.** Comments must use different words than the entity they describe.

| Bad | Good |
|-----|------|
| `# Gets user` for `getUser()` | `# Fetches user from cache, falling back to DB` |
| `# Process data` | `# Processes data in chunks to stay under memory limit` |
| `i++ // increment i` | Don't comment this at all |

### Comment Anti-Patterns

| Anti-Pattern | Example | Problem |
|--------------|---------|---------|
| Repeat the code | `i++ // increment i` | Zero value |
| State the obvious | `// loop through users` | Noise |
| Stale comment | Comment says X, code does Y | Dangerous |
| TODO forever | `// TODO: fix this` (no owner, no date) | Clutter |
| Commented-out code | Dead code as comment | Confusion |

### Patterns That Add Value

| Pattern | Example |
|---------|---------|
| Explain rationale | `// Use insertion sort: n < 10 always` |
| Warn about non-obvious | `// Must call before X, else crash` |
| Summarize algorithm | `// Binary search on sorted timestamps` |
| Document edge case | `// Empty list returns -1, not null` |
| Reference external | `// Per RFC 7231 section 6.5.4` |

---

## Variable Comment Checklist

For each variable, answer in the comment:

- [ ] What are the units? (seconds? milliseconds? bytes?)
- [ ] Are boundaries inclusive or exclusive?
- [ ] What does null mean, if permitted?
- [ ] Who owns the resource (responsible for freeing/closing)?
- [ ] What invariants always hold?

**Goal:** Comment should be complete enough that readers never need to examine all usage sites.

---

## Naming Principles

### Two Required Properties

| Property | Requirement | Test |
|----------|-------------|------|
| **Precision** | Name clearly conveys what entity refers to | "Can someone seeing this name in isolation guess what it refers to?" |
| **Consistency** | (1) Always use this name for this purpose (2) Never use it for other purposes (3) All instances have same behavior | Check all usages |

### Naming Procedure

```
1. Name Evaluation Test:
   "If someone sees this name without declaration or context,
   how closely can they guess what it refers to?"

2. Precision Check:
   - Could this name refer to multiple things? -> Too vague
   - Does this name imply narrower usage than actual? -> Too specific
   - Target: name matches actual scope exactly

3. Consistency Check:
   - Is this name used everywhere for this purpose?
   - Is this name used ONLY for this purpose?
   - Do all variables with this name behave identically?
```

### Common Naming Mistakes

| Mistake | Example | Fix |
|---------|---------|-----|
| Vague status words | `blinkStatus` | `cursorVisible` |
| Too generic | `getCount()` | `numActiveIndexlets` |
| Too specific | `delete(Range selection)` | `delete(Range range)` if it works on any range |
| Similar names, different things | `socket` vs `sock` | Distinct, descriptive names |
| Type in name | `strName` | Just `name` |
| Class repeated in variable | `File.fileBlock` | `File.block` |

---

## Red Flags (Code Clarity)

| Red Flag | What It Signals |
|----------|-----------------|
| Comment repeats code | Rewrite with different words |
| Hard to describe | Design problem -- fix the design |
| Hard to pick name | Design smell -- entity lacks clean design |
| Vague name (`status`, `flag`, `data`) | Conveys little information |
| Interface describes implementation | Shallow abstraction |
| Implementation contaminates interface | Violates separation of concerns |

---

## README Accuracy Checklist

- [ ] Does README describe current behavior?
- [ ] Are setup instructions still valid?
- [ ] Do examples still work?
- [ ] Are dependencies current with package manifests?
- [ ] Is the feature list accurate?

---

## Changelog Update Checklist

- [ ] Breaking changes documented with migration instructions?
- [ ] New features listed with usage examples?
- [ ] Bug fixes noted with issue references?
- [ ] Version number bumped if needed?

---

## AI Documentation Audit

Check any AI config files that exist in the project (`CLAUDE.md`, `AGENTS.md`, editor rule files such as `.cursorrules`, `.windsurfrules`, `.clinerules`, `.roomodes`, and similar):

- [ ] AI docs reflect current architecture?
- [ ] Agent/skill descriptions accurate?
- [ ] File structure documentation up to date?
- [ ] All AI config files consistent with each other?
- [ ] Version numbers synchronized across docs and manifests?

---

## Severity Guide

| Finding | Severity |
|---------|----------|
| README contradicts actual behavior | CRITICAL |
| API doc says wrong return type | CRITICAL |
| Stale comment causes bug risk | CRITICAL |
| CLAUDE.md describes deleted/renamed files | CRITICAL |
| New public API undocumented | IMPORTANT |
| Breaking change not in changelog | IMPORTANT |
| CLAUDE.md missing new features/agents | IMPORTANT |
| AI doc version mismatch | IMPORTANT |
| Stale TODO from distant past | SUGGESTION |
| Could add clarifying comment | SUGGESTION |
| Minor README improvement | SUGGESTION |

---

Detailed checklists for code review: `Read(${CLAUDE_SKILL_DIR}/checklists.md)`

---

## Chain

| After | Next |
|-------|------|
| Code written or changed | Audit using this skill + `${CLAUDE_SKILL_DIR}/checklists.md` |
| Docs verified | Done (pre-commit gate) |