Inline Commenting Convention

A reusable AI-agent skill for keeping code changes understandable.

This package teaches agents to add intent-focused inline comments for non-trivial logic while avoiding noisy, redundant overcommenting. It is designed for Codex-style skills, but the guidance is portable across projects and reusable in other AI harnesses by copying the core rules into repo instruction files.

SKILL.md is the source of truth. Keep README.md and the files in snippets/ as shortened mirrors of that canonical policy.

What It Helps With

Use this convention when code changes include:

• business rules that are not obvious from names alone
• timing-sensitive behavior like retries, delays, suppression windows, expiry windows, or backoff
• state coordination across listeners, caches, subscriptions, or multiple data sources
• auth, permission, onboarding, navigation, or verification gates
• render guards that prevent loops, flicker, stale UI, or duplicate work
• platform-specific workarounds
• fake or dev tooling that intentionally mirrors production behavior
• bug fixes whose original failure mode would be hard to infer later

Public App API JSDoc

Public application APIs carry the strictest documentation standard.

Treat these as public app APIs:

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

For these 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 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 with behavior, fallback semantics, side effects, or constraints that are not obvious from the type. @returns is not required for React components unless the return value itself is part of the caller-facing contract.

Tests, scripts, migrations, and tooling stay judgment-based: document exported or shared helpers when their contract is subtle or reused across files.

Core Principle

Comment the tricky part, not the obvious part.

Prefer one strong comment that explains intent over many weak comments that narrate the code.

Files

• SKILL.md: the agent-facing skill definition
• README.md: human-facing overview and adoption notes
• examples/: before/after examples for the convention
• snippets/: repo instruction snippets for AGENTS.md or CLAUDE.md

Installing In Codex

Copy this folder into your Codex skills directory, for example:

cp -R inline-commenting-convention ~/.codex/skills/

Then reference or rely on the skill in Codex sessions.

Using In Other AI Harnesses

If your harness does not support Codex skills, copy the contents of one of the snippets into the project's instruction file:

• snippets/AGENTS.md
• snippets/CLAUDE.md

Recommended Repo Structure

inline-commenting-convention/
├── SKILL.md
├── README.md
├── examples/
│   └── before-after.md
└── snippets/
    ├── AGENTS.md
    └── CLAUDE.md

Publishing Notes

Recommended next steps:

1. cd inline-commenting-convention
2. review the examples against the latest SKILL.md
3. commit the package
4. push to GitHub

License

MIT.