Back to Details

explaining-code

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Explaining code

解释代码

Explain a specific change or piece of code to a reader new to it, at the Brief or Full depth.
When the question is how a whole subsystem works (its architecture, data flow, and file map), call the Skill tool with 
explaining-architecture
instead. If that skill is not installed, explain at the chosen depth, scoped to the question. Without a Skill tool, follow the skill call rules.
向初次接触相关代码的读者解释一项特定变更或一段代码，深度分为 Brief 或 Full。
当问题涉及整个子系统如何工作（其架构、数据流和文件结构）时，应调用 Skill 工具并使用 
explaining-architecture
。如果未安装该 Skill，则按照所选深度解释，但范围应限定在问题涉及的范围内。如果没有 Skill 工具，请遵循 Skill 调用规则。

Input

输入

The request holds an optional depth token followed by the subject: a PR number or URL, a file path, a function or class name, a branch name, or a concept.
STOP when the request names no subject and the conversation makes none clear. Ask once what to explain, and do no work until the user answers. Explain what the code does, not what its docs claim, and report any disagreement per the docs and code rules.
请求包含一个可选的深度标记，后接解释对象：PR 编号或 URL、文件路径、函数或类名、branch 名称或 concept。
停止操作：如果请求没有指定解释对象，且对话中也无法明确确定解释对象，则询问一次需要解释什么，并在用户回答前不执行任何工作。解释代码的实际行为，而不是复述其文档声称的内容；如果二者存在分歧，请按照 文档与代码规则 报告。

Depth

深度

  • Brief (the default): follow the Brief section below.
  • Full (ELIE): selected by a leading 
    elie
    or 
    eliet
    token, or by a request for ELIE, an explanation "for an engineer" or "for a reviewer", an "in depth" explanation, or the full explanation. Read full explanation and follow it instead of the Brief section.
Drop the depth token before reading the subject.
  • Brief（默认）：遵循下方的 Brief 部分。
  • Full（ELIE）：由开头的 
    elie
    或 
    eliet
    标记选择，也可由用户要求 ELIE、面向“工程师”或“评审者”的解释、“深入”解释或完整解释来选择。阅读 完整解释并遵循其中说明，而不是 Brief 部分。
读取解释对象前，先去掉深度标记。

Brief

Brief

  • Lead with a one-sentence summary that a developer with no context on this area understands.
  • Use concrete nouns ("the order history page", "the login screen"), not abstract ones ("the component", "the module").
  • Use an everyday analogy only when one fits naturally.
  • Follow with 3 to 6 sentences that answer the implicit follow-ups: what the situation was before, what changed, and why.
  • The whole Brief reply is the lead plus those sentences, at most seven sentences in one or two paragraphs, with no headings, bold labels, or bullet lists. Count the sentences before replying.
  • Write more only on request.
  • Spell out and define an unavoidable term or acronym inline at its first use, as in "the SLA (service-level agreement) checker".
  • Cover what and why, not how.
  • Leave out the tests, reviewer notes, risks, edge cases, and implementation detail such as algorithms, comparisons, headers, status codes, and function names; those belong to Full.
  • If they would help, end with one line offering the full explanation.
  • Summarize the effect instead of listing every file touched.
  • Match the scope of the explanation to the question: asked about one function, explain that function, not the whole system.
  • Fit the sentence order to the subject. A PR's sentences run before, then after; a concept may be one paragraph; and a module overview may name its responsibilities in prose.
An illustrative Brief explanation of a PR:
The search page now remembers recent results for one minute, so repeat searches load instantly. Before, every search queried the database, even when the same query ran seconds earlier. Now a results cache (a short-lived in-memory copy of recent answers) is checked first, and the database is queried only on a miss. Results can be up to a minute stale, which the PR accepts because listings change rarely.
  • 开头用一句话概括结论，使不了解该领域上下文的开发者也能理解。
  • 使用具体名词（“订单历史页面”“登录界面”），不要使用抽象名词（“组件”“模块”）。
  • 仅在自然贴切时使用日常类比。
  • 随后用 3 到 6 个句子回答隐含的追问：之前的情况是什么、发生了哪些变化、为什么要这样更改。
  • 完整的 Brief 回复应由开头的一句话和后续这些句子组成，最多七句话，分成一到两个段落，不使用标题、粗体标签或项目符号列表。回复前先计算句子数量。
  • 仅在用户提出要求时再扩写。
  • 对不可避免的术语或缩写，在首次出现时以内联方式拼写并解释，例如“SLA（service-level agreement，服务级别协议）检查器”。
  • 说明“做了什么”和“为什么”，而不是“如何实现”。
  • 不包含测试、评审意见、风险、边界情况或算法、比较、标头、状态码、函数名称等实现细节；这些内容应放在 Full 中。
  • 如果有助于理解，最后可用一行提供完整解释。
  • 总结变更产生的效果，而不是逐个列出涉及的文件。
  • 根据问题确定解释范围：如果问的是某个函数，就解释该函数，而不是整个系统。
  • 根据解释对象调整句子顺序。PR 的说明应依次描述变更前和变更后的情况；concept 可以用一个段落说明；模块概述可以用行文方式概括其职责。
以下是一个 PR 的 Brief 说明示例：
搜索页面现在会将最近一次搜索结果保留一分钟，因此重复搜索可以立即加载。此前，即使相同查询在几秒前刚执行过，每次搜索仍会查询数据库。现在会先检查结果缓存（一份短期保存在内存中的近期结果副本），仅在缓存未命中时查询数据库。结果最多可能过期一分钟；由于列表很少发生变化，PR 接受这种短暂的数据延迟。