coinagerie-define

定义一个词

定义会告诉从未见过这段代码的读者，这个词在此处是什么意思。之所以需要术语表，是因为不加说明的话，每位读者都会从用法中推断出不同含义；因此，定义代表了代码库所认可的解读。

定义包含什么

按顺序最多包含三个部分，每部分一两句话：

1. 此处的含义。 说明这个东西在此代码库中是什么、做什么、包含什么或决定什么，具体到读者可以指出它。
2. 与日常英语的区别。 仅当此代码库中的用法与通常含义不同时才写：先说明这个日常词语通常让人联想到什么，再说明此处的用法有何不同。按通常含义使用的词只写第 1 部分，且应简短；为了套用模板而强行对比会造成误导。
3. 它的位置。 通过符号和文件（hold.service.ts 中的 HoldService）或文件夹，指出定义它的代码。名称比某次编辑更长久；行号则不然。只指出定义所在的位置，而非每个使用处。

不要复述词头。 从句子中删去词头，剩下的内容仍必须表达一些信息。“保留就是用来保留东西的”不合格；用一个本身未定义的同义词来定义也不合格。

- **hold**: A reservation that keeps one copy aside for one patron until
  pickup. Everyday "hold" suggests a grip or a delay; here it is a record with
  an expiry, never an action. Created by `HoldService` in `hold.service.ts`;
  its lifetime is `HOLD_WINDOW` in `hold.constants.ts`.

流程

1. 找出缺漏。 Markdown 中只有 - **word**: 的条目和 JSON 中值为 "" 的条目都属于未定义项（coinagerie-collect 技能会列出它们）。从承载领域含义的词开始。普通编程词（index、value）用一句简短的话定义；如果它们在此处从不表示特定含义，则将其放入 exclude.words。
2. 找到词的定义所在。 搜索词头及其各种形式。词头会进行词形归并：settings 会以 set 列出，复数会归为单数，configured 会归为 configure。也要在标识符中搜索：CallGateService 中包含 gate。查找以该词命名的类型、类、常量、文件夹或文件，然后查看代码旁的文档，以及展示其用法的测试。
3. 只写代码所体现的内容。 错误的定义比空条目危害更大；至少空条目还能被查到。如果代码没有清楚说明其含义，就让条目保持空白，并在报告中说明。
4. 存在多种含义时。 定义主要含义，并在同一定义中指出其他含义。只在更大名称中起补全作用的词（如 HoldService 中的 service），应根据此代码库对该后缀的用法来定义。
5. 检查文件是否仍能解析。 运行 coinagerie --check。定义不会改变检查结果，但解析失败会在检查中显示。

格式

• Markdown：- **word**: Definition. 后续行各缩进至少一个空格。区块中任何顶格行都会被拒绝。缩进行可以包含子条目，也可以用空行分隔缩进段落。定义可以从空条目的下一行开始。
• JSON：值为定义字符串，换行用 \n 表示。
• 按原样保留加粗词头，除非代码中已重命名。其他修改会创建一个新词，而下次运行 --write 时，旧条目及其定义将被删除。
• 一个词若出现在两个术语表中，就在该词列出的术语表中定义。定义不会在不同目标之间复制；通常会从子术语表中排除父术语表已有的词。

常见错误

错误	修正
重述这个词	说明它是什么、做什么或决定什么
解释英文单词的词典释义	在这里给出含义；只有存在差异时才说明区别
逐行解释实现	说明用途；实现方式参见代码
用行号标注位置	使用符号和文件名
把猜测当作事实	暂不说明，直到代码或作者给出说法
长定义中有一行顶格	将所有续行缩进