Inline Docs

Inline Documentation

Documentation remedies ambiguity and supplies missing context. Good code is self-documenting — it shows the what, so a comment must earn its place by adding the why. Keep docs lean.

What to document

• Comment where the code surprises: intent, constraints, workarounds, logic that looks wrong but works. Add the why when it spares the reader a wrong guess; let plain code speak for itself.
• Reserve inline comments for genuinely complicated logic; short phrases.
• Mark unfinished work with TODO/FIXME.
• Keep a comment beside its code and revise both in one edit; comments rot as code drifts.
• Write for the future reader, who knows the code but not your session or the surrounding stack: keep comments timeless and self-contained.

How to write it

• Use block doc comments (JavaDoc, JSDoc, docstrings) for the standard, dev-readable format.
• Write like a senior developer: terse fragments, human names, specific over generic.
• Every comment is signal: cut the noise (keeps, so, because, stays), and prefer commas and semicolons to full sentences.
• Shun ceremony: structure speaks for itself, so section headers like // -------- Variables -------- only bloat tokens.
• Use typeable ASCII only; it keeps docs easy to edit.

Language References

Load in the specific documentation standard(s) for the current project:

| Language | Reference | | --- | --- | | JavaScript/TypeScript | [JSDoc](jsdoc.md) |

Source & license

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

• Author: ethan-ngai
• Source: ethan-ngai/skills
• License: MIT
• Homepage: https://skills.sh/ethan-ngai/skills

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