菜单
What earns a comment, what never belongs in one, and what to do when two distant things must change together. Load before writing or changing any comment or docstring. Language-agnostic.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
基于 SOC 职业分类
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/ponylang/llm-skills --skill pony-comments命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | pony-comments |
| description | What earns a comment, what never belongs in one, and what to do when two distant things must change together. Load before writing or changing any comment or docstring. Language-agnostic. |
| disable-model-invocation | false |
A comment is forever. The code around it moves, the tests move, the build moves, and the comment stays exactly as written with nothing to tell you it started lying. Comments have no tests. Write accordingly.
Load pony-prose first: it is the rulebook for how the words read, in a comment or anywhere else. This skill is the rulebook for what earns a comment at all. The editor persona in pony-code-review checks changed prose against both.
Most comments restate the line beneath them, and the line already said it. Before writing one, try renaming the thing instead. A better name is a comment that cannot go stale.
Write a comment only for a fact a reader needs, that changes a decision they face, and that they can't get from the code in front of them. Name the reader and the decision before you write; if you can't name them, the comment is aimed at nobody — delete it.
The debugging session is the trap. You come out of it with two things that are easy to confuse: the invariant that held, and the sequence of calls that produced it. The invariant is durable — write it. The call sequence describes the current body, and the moment someone rewrites it, the comment is false. You reach for the call sequence because it cost the most to learn, which is the wrong reason to write anything down.
A comment outlives the machinery around it. These all rot:
Every one becomes false the moment somebody edits a workflow or deletes a test, and nothing catches it.
Run this check before you write, not after. It costs nothing:
If deleting a test or editing a workflow would make this sentence false, it does not belong in a comment.
The information is still worth having. It belongs where the machinery is documented and maintained: the build file, the CI config, the project's AGENTS.md. If it is the AGENTS.md, load pony-agents-md first — that file is read on every task in the repository, and it has its own bar for what earns a line.
One word needs care. "Silently" is a fact about the program when it means the code produces a wrong value and raises nothing. It is a shelf-life claim when it means no test catches it. Only the first belongs in a comment.
The same rot has an inside form, and it is the more tempting one. A comment that describes how the current body does its work — "walks the list twice, once to count" — looks like the safest comment there is, because it is about the code and nothing else. It rots all the same: the moment someone rewrites the body, it's false, and nothing catches it. The check mirrors the one above:
If rewriting the body — without changing anything a caller relies on — would make this sentence false, then it describes how the code works now, not a fact that outlasts the body, and it does not belong in a comment.
One that doesn't is worse than none — it costs the reader effort and returns nothing. The plainness rules that keep a comment legible, including never coining jargon for what the code does, live in pony-prose; load it before writing one.
"Previously this returned -1." "Before the refactor we…" "Added in 0.3." Version control remembers. The next reader does not need it inline.
// WIP. A // TODO: add validation after validation exists. Dated notes. Apologetic stubs. Commented-out code. Section banners the code structure already conveys — a banner survives only when it marks something the structure cannot, like a "do not reorder" boundary.
A thing being used does not need to name who uses it. When the caller names the callee — a call, an import, an include — that reference already records the relationship, and the toolchain follows it. A comment inside the callee listing its callers adds a backward link that isn't in the code, that nothing enforces, and that goes stale the moment the caller set changes. Documenting it that way creates the problem it claims to document.
Keep such a note only when the comment is the relationship's only record: an external, dynamically dispatched, or convention-matched caller that no in-repo reference names — a cron job, a plugin loaded by name, a format two files must agree on.
This is where most bad comments come from. "Coupling" sounds important, and writing one down feels like doing the job well. Usually it isn't one.
Three things, all true at once:
The third is what earns the comment. Standing at one end, you have no way to discover the other exists.
Equality is only one shape the constraint takes:
A call, an import, an include, a shared constant. These are references. The toolchain follows them and keeps both ends together. If one file includes the header that defines the value, the two cannot drift. Ordinary use of a thing is not a coupling.
Both ends in the same file. Local knowledge finds it. If it still needs saying, say it — but it isn't this.
Anything where breaking it only costs speed. A cache that gets rebuilt when cold is slower, not wrong. No constraint was violated.
Reading a field. Calling a function. Implementing an interface. That is code.
Remove it. Make the two ends one end. Unify the duplicated predicate. Generate the mirror from its source. Derive one side from the other. A coupling you delete cannot rot, cannot be missed, and needs no comment.
Pin it. A static assertion, a generated header, a test whose only job is to fail when the constraint breaks. This turns a value into a reference and hands it to the toolchain, which never forgets.
Comment both ends. Only when the first two are genuinely impossible — an FFI boundary between languages, a version string in a container image, a constant two runtimes agree on.
Reach for the comment last. It is what you write when you failed to remove the coupling, not the way to record that you found one.
Three things, and nothing else:
Put one at each end. Nothing about tests, nothing about CI, nothing about which suite to run.
Whether the coupling can be tested is a real question and a separate one. If it can, test it — that is the second rung. If it cannot, say so to a human in the pull request, where it gets read once and acted on, not in a comment that will outlive the reason.
They are for the people using the thing, not the people maintaining it. Write them fully — "default: don't" does not apply. The rules above about shelf life and history still do, as do all of pony-prose's.
Full does not mean padded. A docstring gives a caller what they need to use the thing correctly: what it does, and the guarantees they can rely on. It says nothing about how it works, and it doesn't restate the signature.
In Pony, \nodoc\ on test declarations is load-bearing tooling, not prose. Never remove it.
For the avoidance of doubt, keep:
TODO or FIXME tied to a live issueEnsemble code review with specialized reviewer personas. Has full (9-persona) and lightweight (4-persona) modes. Load when conducting a code review of a PR, branch, or local changes.
Two-stage ensemble for planning meaningful tests. Load when writing tests for new features or reviewing test quality. Counters the tendency to write tests that exercise the stdlib instead of your code. Has full (9-persona) and lightweight (5-persona) modes.
Load the Pony language reference (capabilities, PonyCheck, stdlib pitfalls, mort pattern). Load it before Pony coding sessions.