express-intent-in-codelisted

意図は名前・型・構造で表明し、コードから読めない why だけを残す。 ## インライン処置の範囲 (redundancy-guard hook からの合流) **1〜2 行のコメント判定**はインラインでよい。次の場合は該当する梯子を使う: - 新規 helper / util / ファイルの追加 (→ 再利用梯子) - 命名の変更・新設 (→ 命名梯子) - lint suppression の追加 - 3 行以上のコメント追加 コメント率ではなく、変更後に残るコメントと昇格可能性を判定する。 ## 書く前の再利用梯子 (最初に該当した段で止める) 新しい関数・ヘルパー・ファイルを書く前に順に問う: ⓪そもそも要るか → ①コードベースに既にあるか → ②言語標準 → ③プラットフォーム標準 → ④導入済み依存 → ⑤最小コード。suppression を書く前にも①を確認する。 ## 命名梯子 (飛び級禁止、1 段ずつ) 段0 機構/ノイズ語 (`bbox_xhtml`, `data`, `tmp`) → 段1 正直な what (`word_coordinate_data`) → 段2 嘘の除去 (名前に出ない副作用・前提を名前へ) → 段3 目的名 (`signature_anchor_boxes`) → 段4 ドメイン語 (`signing_positions`)。 - 段3 へ上げる前に**全 caller を観測**し、用途を 1 動詞句で言語化する (読まずにでっち上げない)。caller ごとに用途が割れるなら改名でなく分離する。 - 段4 は実在するドメイン語への接地が条件。慣用ロール接尾辞は、入出力契約に合い、競合する既存語が別の意味を持つ場合に使える。ほかは段3で止める。 ## 凝集性 - 独立に変化する作用は分ける。 - 一つの不変条件を成立させる作用は、分離に調整状態が要るならまとめる。 - 選択した指摘と無関係な整理を混ぜない。 ## コメントの判定 書く前に (または hook に指摘されたら) 昇格を試みる: | コメントが説明しているもの | 昇格先 | |---|---| | 値の正体・データ形状 | 型 / 値オブジェクト | | 用途・存在理由 | 名前 (目的名) | | 分岐理由・複合条件 | 述語メソッド / 説明変数 | | マジック値の意味 | 定数 | | 手順の段落・機構 | 意図名の private へ抽出 | | boolean 引数の意味 | enum / シンボル | | null / undefined の意味差 | 判別可能 union | | 禁止規律・不変条件 (「〜しないこと」「〜が成り立つ前提」) | 静的テスト (grep tripwire) / ast-grep / lint ルール | 禁止規律の昇格先���再利用梯子で既存前例を探してから 1 つ選ぶ。2 つ目を重ねるのは、1 つ目が検出できない失敗モード (設定ごと削除・定義自体の消失等) を具体的に言えるときだけ。 **残す = 真の why 4 類型 + 正本参照 1 文**: 外部仕様・他システム前提 / 実測根拠・トレードオフ数値 / 危険・順序依存・セキュリティ判断 / FIXME (理想 + 妥協理由)。名前付き定義の直上1箇所に置き、昇格時は担い手へ移す。外部制約・順序依存と私有名詞化できる手順詳細が同じコメントに混在するときは、手順詳細だけを意図名の privat