Skip to content
Skills Library
Programming · Writing

code-comments

/code-comments

Write clear, plain-spoken code comments and documentation that lives alongside the code. Use when writing or reviewing code that needs inline documentation—file headers, function docs, architectural decisions, or explanatory comments. Optimized for both human readers and AI coding assistants who benefit from co-located context.

Repository
dotfiles ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Write clear, plain-spoken code comments and documentation that lives alongside the code. Use when writing or reviewing code that needs inline documentation—file headers, function docs, architectural decisions, or explanatory comments. Optimized for both human readers and AI coding assistants who benefit from co-located context.

Original author description

Write clear, plain-spoken code comments and documentation that lives alongside the code. Use when writing or reviewing code that needs inline documentation—file headers, function docs, architectural decisions, or explanatory comments. Optimized for both human readers and AI coding assistants who benefit from co-located context.

How it works

  1. Core Philosophy
  2. Documentation Levels
  3. Language-Specific Patterns
  4. Writing Style
Original SKILL.md headings · 194 lines, 975 words
SKILL.md preview
---
name: code-comments
description: Write clear, plain-spoken code comments and documentation that lives alongside the code. Use when writing or reviewing code that needs inline documentation—file headers, function docs, architectural decisions, or explanatory comments. Optimized for both human readers and AI coding assistants who benefit from co-located context.
---

# Code Comments

Write documentation that lives with the code it describes. Plain language. No jargon. Explain the *why*, not the *what*.

## Core Philosophy

**Co-location wins.** Documentation in separate files drifts out of sync. Comments next to code stay accurate because they're updated together.

**Write for three audiences:**
1. Future you, six months from now
2. Teammates reading unfamiliar code
3. AI assistants (Claude, Copilot) who see one file at a time

**The "why" test:** Before writing a comment, ask: "Does this explain *why* this code exists or *why* it works this way?" If it only restates *what* the code does, skip it.

## Documentation Levels

### File Headers

Every file should open with a brief explanation of its purpose and how it fits into the larger system.

```typescript
// UserAuthContext.tsx
//
// Manages authentication state across the app. Wraps the root component
// to provide login status, user info, and auth methods to any child.
//
// Why a context instead of Redux: Auth state is read-heavy and rarely
// changes mid-session. Context avoids the ceremony of actions/reducers
// for something this simple.
```

```swift
// NetworkRetryPolicy.swift
//
// Handles automatic retry logic for failed network requests.
// Uses exponential backoff with jitter to avoid thundering herd
// when the server comes back online after an outage.
//
// Used by: APIClient, BackgroundSyncManager
// See also: NetworkError.swift for error classification
```

**Include:**
- What this file/module is responsible for
- Why it exists (if not obvious from the name)
- Key relationships to other parts of the codebase
- Any non-obvious design decisions

### Function & Method Documentation

Document the contract, not the implementation.

```typescript
/**
 * Calculates shipping cost based on weight and destination.
 *
 * Uses tiered pricing: under 1lb ships flat rate, 1-5lb uses
 * regional rates, over 5lb triggers freight calculation.
 *
 * Returns $0 for destinations we don't ship to rather than
 * throwing—caller should check `canShipTo()` first if they
 * need to distinguish "free shipping" from "can't ship."
 */
function calculateShipping(weightLbs: number, zipCode: string): number
```

```python
def sync_user_preferences(user_id: str, prefs: dict) -> SyncResult:
    """
    Pushes local preference changes to the server and pulls remote changes.

    Conflict resolution: server wins for security settings, local wins
    for UI preferences. See PREFERENCES.md for the full conflict matrix.

    Called automatically on app foreground. Can also be triggered manually
    from Settings > Sync Now.
    """
```

**Include:**
- What the function accomplishes (not how)
- Non-obvious parameter constraints or edge cases
- What the return value means, especially for ambiguous cases
- Side effects (network calls, file writes, state mutations)

**Skip for:** Simple getters, obvious one-liners, private helpers with descriptive names.

### Inline Comments

Use sparingly. When you need them, explain the reasoning.

```typescript
// Debounce search by 300ms to avoid hammering the API on every keystroke.
// 300ms feels responsive while cutting API calls by ~80% in user testing.
const debouncedSearch = useMemo(
  () => debounce(executeSearch, 300),
  [executeSearch]
);
```

```swift
// Force unwrap is safe here—viewDidLoad guarantees the storyboard
// connected this outlet. If it's nil, we want to crash immediately
// rather than fail silently later.
let tableView = tableView!
```

```python
# Process oldest items first. Newer items are more likely to be
# modified again, so processing them last reduces wasted work.
queue.sort(key=lambda x: x.created_at)
```

### Architectural Comments

For code that embodies important design decisions, explain the tradeoffs.

```typescript
// ARCHITECTURE NOTE: Event Sourcing for Cart
//
// Cart state is rebuilt from events (add, remove, update quantity)
// rather than stored directly. This lets us:
// - Show complete cart history to users
// - Replay events for debugging
// - Retroactively apply promotions to past actions
//
// Tradeoff: Reading current cart state requires replaying all events.
// We cache the computed state in Redis with 5min TTL to keep reads fast.
// Cache invalidation happens in CartEventHandler.
```

```swift
// WHY COORDINATOR PATTERN
//
// Navigation logic lives here instead of in view controllers because:
// 1. VCs don't need to know about each other (loose coupling)
// 2. Deep linking becomes straightforward—just call coordinator methods
// 3. Navigation is testable without instantiating UI
//
// The tradeoff is more files and indirection. Worth it for apps with
// 10+ screens; overkill for simple apps.
```

### TODO Comments

Make them actionable and traceable.

```typescript
// TODO(pete): Extract to shared util once mobile team needs this too.
// Blocked on: Mobile API parity (see MOBILE-123)

// HACK: Workaround for Safari flexbox bug. Remove after dropping Safari 14.
// Bug report: https://bugs.webkit.org/show_bug.cgi?id=XXXXX

// FIXME: Race condition when user rapidly toggles. Need to cancel
// in-flight requests. Reproduced in issue #892.
```

## Language-Specific Patterns

See [references/language-examples.md](references/language-examples.md) for detailed examples in:
- TypeScript/JavaScript (JSDoc, TSDoc patterns)
- Swift (documentation comments, MARK pragmas)
- Python (docstrings, type hint documentation)
- React/Next.js (component documentation patterns)

## Writing Style

**Plain language.** Write like you're explaining to a smart colleague who doesn't have context.

**Active voice.** "This function validates..." not "Validation is performed..."

**Be specific.** "Retries 3 times with 1s backoff" not "Handles retries."

**Skip the obvious.** If the code says `user.isAdmin`, don't comment "checks if user is admin."

**Date things that expire.** Workarounds, version-specific code, and temporary solutions should note when they can be removed.

**Reference constants, don't duplicate values.** When a behavior is controlled by a constant, reference it by name—don't restate its value in the comment.

```rust
// Bad: duplicates the value, will drift when constant changes
/// Returns true if stale (not updated in last 5 minutes)
pub fn is_stale(&self) -> bool { ... }

// Good: references the constant
/// Returns true if stale (not updated within [`STALE_THRESHOLD_SECS`])
pub fn is_stale(&self) -> bool { ... }
```

Unit translations for magic numbers are fine (`1048576 // 1MB`) since they add clarity, not duplication.
Files in this package (2)
  • SKILL.md 7 KB
  • references/language-examples.md 11 KB

Versions

RepositoryScoreLicence
This page · zenobi-us/dotfiles100MIT
rp1-run/rp1100Apache-2.0
petekp/claude-code-setup100MIT
portabletext/editor100MIT
caidanw/skills100MIT
caidanw/skills100MIT
izumin5210/dotfiles95MIT
overmind-core/overmind90AGPL-3.0
Amey-Thakur/AI-SKILLS90MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 3ffc5ebecdaf (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100code-documentation
    Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.
  • 100documentation
    Creates clear, comprehensive documentation. Use when writing READMEs, API docs, code comments, or user guides. Follows documentation best practices.
  • 100technical-writing
    Rule set for text people read — docs, READMEs, doc comments (Javadoc, docstrings), inline comments, commit bodies, MR/PR descriptions, error messages, release notes, and comments posted to chat or a tracker. Use when writing or rewriting any of these, when asked to make text…
  • 100agent-documentation-writer
    Specialist subagent: Generates comprehensive documentation including READMEs, API docs, architecture docs, and inline comments. Use when documenting code, creating guides, or explaining systems.
  • 100documentation
    In-code documentation, folder READMEs, code comments. Use when: "document this", "add JSDoc", "write a README", "explain this code", or writing README.md/JSDoc.
  • 100common-documentation
    Write effective code comments, READMEs, and technical documentation following intent-first principles. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.