coinagerie-define

単語の定義

定義とは、このコードを初めて見る読者に、この場所でその単語が何を意味するかを伝えるものです。用語集があるのは、そうでなければ読者ごとに使われ方から異なる意味を推測するためです。したがって、定義はコードベースが支持する唯一の読み方です。

定義に含める内容

以下のうち最大3つを、この順番で、それぞれ1〜2文で記述します。

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）は短い文を1つ記述するか、このコードベースで固有の意味を持たない場合はexclude.wordsに含めます。
2. 単語の定義場所を探します。 見出し語とその語形を検索します。見出し語は語形をまとめて扱います。settingsはsetとして掲載され、複数形は単数形、configuredはconfigureとして扱われます。識別子の中も検索します。CallGateServiceにはgateが含まれています。その単語にちなんだ名前の型、クラス、定数、フォルダー、ファイルを探し、そのコードに付随するドキュメントや、使用例がわかるテストも確認します。
3. コードに示されていることだけを書きます。 誤った定義は、何もない箇条書きよりも害があります。何もない箇条書きなら、少なくとも見つけることはできます。コードから意味が明らかでない場合は、箇条書きを空のままにして、その旨を報告してください。
4. 複数の意味がある場合。 主な意味を定義し、同じ定義内で別の意味にも言及します。大きな名前を構成するだけの単語（HoldServiceのserviceなど）は、このコードベースで接尾辞がどのように使われるかによって定義します。
5. ファイルを正しく解析できるか確認します。 coinagerie --checkを実行します。定義によってチェック結果が変わることはありませんが、解析エラーがあればそこで検出されます。

形式

• Markdown：- **word**: 定義。と記述します。続きは次の行に記述し、各行を1つ以上のスペースでインデントします。ブロック内で左端から始まる行は拒否されます。インデントした行にはサブ箇条書きを含めることができ、インデントした段落の間には空行を入れることができます。定義は、空の箇条書きの次の行から始めてもかまいません。
• JSON：値は定義文字列です。改行には\nを使います。
• 太字の見出し語は、コード内で名前が変更された場合を除き、記載どおりにしてください。 それ以外の編集は新しい単語を作ることになり、次の--writeで元の箇条書きとその定義が削除されます。
• ある単語が2つの用語集に掲載されている場合は、掲載されている用語集で定義します。定義が別の場所にコピーされることはありません。親用語集ですでに定義されている単語は、通常、子用語集では除外します。

よくある間違い

間違い	修正
単語を言い換えるだけ	それが何か、何をするか、何を決定するかを説明する
英単語の辞書的な意味	ここでの意味を示し、異なる場合にのみ対比を示す
実装を行ごとに説明する	何のためのものかを述べ、方法はコードを参照する
場所として行番号を示す	シンボル名とファイル名
推測を事実として述べる	コードまたは作者が示すまでは、推測を述べない
長い定義で行頭に置かれた行	続くすべての行をインデントする