Back to Details

code-naming

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Naming

Code Naming

名前の目的は、利用者が対象を正しく識別できることである。最短の名前や、宣言元でだけ自然な名前を目標にしない。実際の参照箇所で必要な意味を保ち、そこですでに明らかな語だけを削る。
The purpose of a name is to enable users to correctly identify its target. Do not aim for the shortest name or one that is only natural at the declaration site. Preserve the meaning required at actual reference sites, and remove only words that are already clear there.

1. 文脈を調べる

1. Investigate the context

新規命名・レビュー・リネームの前に、判断に必要な範囲で確認する。
  • repositoryの既存規約、対象言語・frameworkの命名制約、隣接する名前
  • 対象の責務・実際の値や振る舞い・同階層で区別すべき概念
  • 宣言元だけでなく、representativeな参照箇所とimport / export形態
  • 公開API、schema、永続化データ、CLI、file pathなど、名前が外部契約になっているか
Before creating, reviewing, or renaming anything, confirm the information needed to make a judgment within the relevant scope.
  • Existing repository conventions, naming constraints imposed by the target language or framework, and neighboring names
  • The target's responsibilities, actual values or behavior, and concepts that must be distinguished within the same hierarchy
  • Representative reference sites and import / export patterns, not just the declaration site
  • Whether the name forms part of an external contract, such as a public API, schema, persisted data, CLI, or file path

2. 名前を評価する

2. Evaluate the name

以下を満たす最小限の情報で命名する。
  • 意味: 動作、役割、ドメイン概念が分かる。抽象語だけで意味を覆い隠さない
  • 区別: 同じscopeや利用場面にある別の対象と誤認しない
  • 重複: 使用箇所のnamespace、receiver、型、pathなどから自明な情報を繰り返さない。ただし宣言元のpathが参照箇所でも見えると仮定しない
  • 一貫性: 同じ概念には同じ語を使い、case、複数形、略語、suffixはrepository・言語の慣習に合わせる
  • 安定性: 一時的な実装手段や配置場所ではなく、維持すべき責務に基づいて命名する
短縮した結果、読み手が型、実装元、会話履歴をたどる必要が増えるなら短縮しない。短いlocal変数は文脈で一意ならよいが、公開名は単体でも理解できるようにする。
Choose a name using the minimum amount of information needed to satisfy the following criteria.
  • Meaning: The behavior, role, or domain concept should be clear. Do not conceal meaning behind purely abstract terms.
  • Distinctiveness: The name should not be confused with another target in the same scope or usage context.
  • Redundancy: Do not repeat information that is already obvious from the namespace, receiver, type, or path at the usage site. However, do not assume that a path visible at the declaration site is also visible at every reference site.
  • Consistency: Use the same terminology for the same concept, and follow the repository's and language's conventions for case, plurals, abbreviations, and suffixes.
  • Stability: Base the name on the responsibility that should be maintained, rather than on a temporary implementation approach or location.
Do not shorten a name if doing so would force readers to trace types, implementation sources, or conversation history. A short local variable is acceptable when it is unambiguous in context, but a public name should be understandable on its own.

3. 対象別に判断する

3. Judge by target type

  • ファイル・ディレクトリ: 親pathから分かる語は省けるが、隣接要素との区別と移動後の可読性を保つ。言語・frameworkが規定する 
    page.tsx
    、
    route.ts
    、
    mod.rs
    等は任意に変更しない
  • 関数・メソッド: 実際の操作・変換・副作用を表し、receiverやnamespaceが意味を補う場合は重ねない。曖昧な 
    process
    / 
    handle
    を機械的に許容しない
  • 型・定数・変数: 役割と意味上の区別を優先する。
    data
    / 
    manager
    / 
    util
    / 型名suffixを機械的に削除・禁止しない
  • action・schema・serialization key: 内部の識別子と外部から参照・保存される名前を区別する。後者は変更するとcontract変更になる
  • Files and directories: Words already evident from the parent path may be omitted, but preserve distinction from neighboring elements and readability after moving the file or directory. Do not arbitrarily change names specified by the language or framework, such as 
    page.tsx
    , 
    route.ts
    , or 
    mod.rs
    .
  • Functions and methods: Represent the actual operation, transformation, or side effect. Do not repeat meaning already supplied by the receiver or namespace. Do not mechanically accept vague names such as 
    process
    or 
    handle
    .
  • Types, constants, and variables: Prioritize the role and semantic distinctions. Do not mechanically remove or prohibit names such as 
    data
    , 
    manager
    , 
    util
    , or type-name suffixes.
  • Actions, schemas, and serialization keys: Distinguish internal identifiers from names referenced or persisted by external systems. Changing an externally referenced or persisted name constitutes a contract change.

4. 反例で判断を補正する

4. Use counterexamples to refine judgments

src/workspace/background.ts
内の 
workspaceBackgroundToGridStyle
は重複候補だが、常に 
toGridStyle
がよいわけではない。
ts
// 名前空間が参照箇所で見えるなら短くできる
background.toGridStyle(input);

// 名前空間なしの直接importでは意味を残す
backgroundToGridStyle(input);
一方、
createUser
を 
create
にすると複数の生成処理と区別できない場合がある。短縮を見送るのが正解になるケースを必ず考える。
workspaceBackgroundToGridStyle
in 
src/workspace/background.ts
is a candidate for redundancy, but 
toGridStyle
is not always better.
ts
// It can be shortened when the namespace is visible at the reference site
background.toGridStyle(input);

// It must retain its meaning when directly imported without a namespace
backgroundToGridStyle(input);
On the other hand, changing 
createUser
to 
create
may make the name indistinguishable from multiple creation operations. Always consider cases where declining to shorten the name is the correct decision.

5. リネームするとき

5. When renaming

  1. 変更する名前と実参照を列挙し、意味の改善が明確なものだけを対象にする。無関係な一括短縮をしない
  2. 言語サーバー等のsymbol-aware renameを優先し、曖昧な文字列置換を避ける。path変更ではimport、case-sensitive / insensitive filesystem、build設定を確認する
  3. 型・schema・test・fixture・doc・生成物のsourceなど影響する参照を整合させる。
    rg
    等による文字列検索は探索と残存確認に用い、参照網羅の唯一の根拠にしない
  4. 公開API、persisted key、DB、event、外部連携の名前は原則維持する。変更が必要なら利用者・既存データへの影響を調べ、明示的な移行・alias・codec等で互換性を扱う。内部識別子の短縮に伴ってwire nameまで変えない
  5. 変更に応じたformatter / typecheck / lint / test / contract検証をprojectの定義から選び、対象の参照箇所で名前が改善したことを読み直す
  1. Enumerate the names to be changed and their actual references, and target only changes that clearly improve meaning. Do not perform unrelated bulk shortening.
  2. Prefer symbol-aware rename features provided by language servers, and avoid ambiguous string replacement. When changing paths, check imports, case-sensitive / case-insensitive filesystems, and build configuration.
  3. Align all affected references, including types, schemas, tests, fixtures, documentation, and generated sources. Use string searches such as 
    rg
    for discovery and confirmation of leftovers, but not as the sole evidence that all references have been covered.
  4. In principle, preserve names used by public APIs, persisted keys, databases, events, and external integrations. If a change is necessary, investigate its impact on users and existing data, and handle compatibility through explicit migrations, aliases, codecs, or other appropriate mechanisms. Do not change a wire name merely because an internal identifier has been shortened.
  5. Select formatter / typecheck / lint / test / contract validation defined by the project according to the change, then reread the affected reference sites to confirm that the names have improved.

完了条件

Completion criteria

  • 参照箇所で曖昧さが減り、必要な区別が失われていない
  • 参照と名前の不整合・取り残しがない
  • external / persisted contractが維持されたか、変更と移行が明示されている
  • 変更規模に応じたverification evidenceがある
改善を説明できないリネームは行わない。報告は主要な変更、互換性への影響、検証結果に絞る。
  • Ambiguity has been reduced at reference sites without losing necessary distinctions.
  • There are no inconsistencies or leftovers between references and names.
  • External / persisted contracts have either been preserved, or the changes and migrations have been made explicit.
  • Verification evidence is appropriate to the scale of the change.
Do not perform a rename when its improvement cannot be explained. Limit the report to the primary changes, compatibility impact, and verification results.

補助資料

Supporting references

言語ごとの詳細規約は当該projectの採用言語・frameworkを優先する。参考:
For detailed conventions specific to a language, prioritize the languages and frameworks adopted by the project. References: