# Code Comments

> Use before committing any code change in this repository — Go, TypeScript templates, shell scripts, YAML, mise tasks — and when reviewing a diff for comment noise. Triggers on writing or keeping `//` or `#` comments, doc comments, "why" explanations, reviewer notes, TODO/history notes, or comments that restate a name.

- Skill: `speakeasy-api/code-comments` (Agent Skill)
- Install (CLI): `npx skillmds@latest add speakeasy-api/code-comments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/speakeasy-api/code-comments/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: speakeasy-api (https://skillmd.com/u/speakeasy-api)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/speakeasy-api/code-comments

---


# Code comments

No narrative comments in code. Constants/functions with clear names get no
comment; never annotate why a change was made or explain design in comments.

**Why:** "this is not your diary, it's a codebase" — comments talking to the
reviewer are noise post-merge.

**How to apply:** Write comments only for non-obvious constraints the code
cannot possibly express; match existing file density.