Inline Commenting Convention

Inline Commenting And JSDoc Convention

Goal

Leave changed code easier to understand, easier to call correctly, and safer to change than you found it.

Add succinct inline comments for non-trivial logic you introduce or materially change. Favor comments that explain intent, invariants, business rules, timing assumptions, race-condition guards, state coordination, navigation/permission gates, platform-specific workarounds, and other logic that would be hard to re-derive quickly from the code alone.

The best comments preserve the "why" at the decision point: what invariant the code protects, which tempting simplification would be unsafe, and how future developers or agents should extend the path without undoing the design.

Use JSDoc for callable contracts. Use inline comments for tricky implementation decisions. A future reader should understand both how to call the code and why the code takes its current shape.

This convention is portable across projects. Keep the core guidance framework-agnostic, and treat this SKILL.md as the source of truth for any README or harness-specific snippets copied from it.

This convention applies to application code, backend code, tests, scripts, infrastructure code, migrations, and development tooling. Public application APIs carry the strictest documentation standard; tests, scripts, migrations, and tooling use the same judgment-based comment rules unless they expose reused helpers with subtle contracts.

Architectural Guardrails

Use comments as guardrails at seams where future edits are likely to look simpler than they are.

Comment these decisions in-place:

• provider, client, auth, session, environment, and backend boundary branches
• fallback paths, guest/local-only modes, migration compatibility, and low-privilege states
• schema-derived state where adding a separate flag would create drift
• ordering requirements between storage, network, cache, navigation, and render state
• tests that protect a subtle regression or historical failure mode

For multi-file architecture decisions, pair one short inline comment near the branch with a small doc or ADR. The inline comment should tell the reader why this code exists now; the doc can explain the wider system.

JSDoc Contracts

Add or refresh JSDoc for public application APIs and for any reused helper whose call contract is subtle.

Public application APIs include:

• exported app functions, hooks, reusable components, and public types
• model helpers, mutations, queries, actions, route handlers, API handlers, and shared utilities
• any exported backend or frontend helper intended to be called outside its defining file or module

For public application APIs, use full JSDoc as the default. Include @param and @returns for functions, hooks, route/API handlers, model helpers, and shared utilities. Include @throws when the API intentionally throws or propagates meaningful errors that callers need to understand.

For public React or UI components, document the component responsibility and props contract. Use @param props plus individual @param props.field entries only for props whose behavior, fallback semantics, side effects, or constraints are not obvious from the type. Do not require @returns for React components unless the return value itself is part of the caller-facing contract.

For tests, scripts, migrations, and development tooling, require JSDoc for exported or shared helpers when they are reused across files or their contract is subtle. Avoid forcing full API-style JSDoc onto one-off local helpers.

Good JSDoc explains the callable contract:

• what the function or type is responsible for
• which inputs matter beyond what TypeScript already says
• what the caller receives, including null/empty/fallback behavior
• which errors can be thrown and when
• which auth, storage, persistence, migration, or low-privilege assumptions apply

For .js and .cjs files, these tags are often the type contract, so include concrete JSDoc types instead of relying on inference that callers and editors may not have.

In TypeScript files, do not let tags become empty ceremony. Full JSDoc is required for public application APIs, but each tag should explain responsibility, constraints, fallback semantics, side effects, or caller expectations rather than merely restating the visible type.

Prefer concise JSDoc at the declaration and a short inline comment inside the body only where the implementation protects a non-obvious invariant.

When to Comment

Add or refresh comments when the change includes:

• public application APIs whose contract is new, changed, or currently undocumented
• exported or shared test, script, migration, or tooling helpers whose contract is subtle or reused across files
• branching business logic that is not obvious from names alone
• retries, delays, suppression windows, expiry windows, backoff, or other timing-sensitive behavior
• listener, subscription, cache, or state coordination across multiple sources
• navigation, auth, permission, onboarding, or verification gates
• provider, auth, schema, or fallback branches that encode architectural decisions
• render or state-management guards that prevent loops, flicker, stale UI, or duplicate work
• platform-specific handling or compatibility workarounds
• fake, mock, or dev tooling whose flow intentionally mirrors production behavior
• bug fixes where the original failure mode would not be obvious to a future reader

When Not to Comment

Do not add comments for:

• obvious assignments
• simple JSX or template structure
• straightforward styling
• one-line helpers whose names already explain the behavior
• comments that merely narrate what the next line literally does
• JSDoc that only restates parameter names or TypeScript-visible types without adding caller-facing meaning

Scope Guard

Do not comment every changed line.

Aim for the smallest number of comments that makes the edited logic understandable. One strong comment that explains the intent of a tricky block is better than five weak comments that restate the code.

If the code is already obvious after good naming and small refactoring, add no comment.

Comment Style

Prefer intent-focused comments over implementation narration.

Good comments explain:

• why this branch exists
• what invariant a guard protects
• why a delay, retry, or suppression window exists
• why a specific order must be preserved
• why a value or reference is intentionally reused to avoid churn
• why a screen, route, or flow is gated more strictly than it first appears
• which attractive refactor would break an invariant
• where a nearby doc carries the broader architecture context

Avoid comments like:

• "set x to y"
• "render the button"
• "loop through the array"
• comments that repeat the function name
• long block comments when one short line would do

Examples

Bad:

• // set timeout
• // render modal
• // update state

Good generic examples:

• /** Resolves the active account from session state and persisted fallback data. */
• @param accountId - Stable account identifier used to load the caller-visible account record.
• @returns The active account record, or null when the caller can continue in local-only mode.
• // Keep the completed request suppressed briefly so backend replay does not reopen the chooser.
• // Reuse the previous array reference so React can skip a no-op rerender.
• // Only hard-block when the server also explains why the user cannot continue.
• // Append follow-up fake records instead of replacing the list so the dev tool mirrors production ordering.
• // Treat the persisted identifier as the source of truth; a separate boolean can drift during account linking.
• // Keep the unauthenticated provider path so local-only profiles can sync before sign-in is configured.

Keep examples generic by default. Domain-shaped examples are useful when they clarify a common pattern, but mark them as domain-specific instead of letting a framework, provider, or product example define the whole convention.

Editing Rule

When you touch an existing complex path, inspect nearby comments too.

• keep helpful comments that are still true
• update stale comments as part of the same change
• add a new comment if the modified logic would be hard to re-derive quickly
• delete comments that are now misleading, redundant, or contradicted by the new behavior

Review Pass

Before finishing:

• scan each edited hunk
• confirm new or changed public application APIs have full useful JSDoc
• confirm exported/shared test, script, migration, or tooling helpers have JSDoc when their contracts are subtle or reused across files
• add comments only where intent is not obvious
• remove or rewrite stale nearby comments
• prefer one strong comment over many weak ones
• place architectural comments next to the branch or invariant they protect
• make sure the final comment still matches the final code after refactors

Final Check

Before you stop, ask:

• would a teammate understand why this logic exists without opening git history?
• would a caller understand the function contract without reading the whole body?
• did I comment the tricky part instead of the obvious part?
• did I warn against the likely wrong simplification?
• did I leave the edited area easier to understand than I found it?

If not, add or refine the comment before finishing.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: akhenda
• Source: akhenda/inline-commenting-convention
• License: MIT

Install and usage instructions live in the source repository linked above.