readable-code

name	readable-code
description	JavaScript, Vue, or Python の実装・修正・小規模整理を、可読性最優先で行うときに使う。最小差分で直しつつ、命名、変数コメント、定数コメント、JSDoc/docstring、説明変数、早期リターンを重視する。単なる調査や雑談では使わない。

目的

1年後の自分や他の人が最短で理解できるコードを優先して実装する。

最重要方針

• 読み手の理解速度を最優先にする
• 名前だけで伝わらない情報はコメントで補足する
• ただし、コードを読めば明らかな逐一説明コメントは禁止
• コメントは「何をしているか」より「何を表すか」「どう使われるか」「なぜそうするか」を優先する
• 既存コードベースの責務分離と API shape は尊重する
• 挙動変更は依頼範囲だけに限定する

変数ルール

• 変数名は具体的にし、役割・対象・必要なら単位が分かるようにする
• tmp, data, info, value, flag, result のような曖昧名は避ける
• 重要な変数には、最初の定義直前でコメントを付ける
• コメントは、後から代入された場所ではなく最初に意味が確定する箇所へ付ける
• 状態保持変数、store/state、nullable、sentinel 値、単位依存値、分岐で重要な変数は特に丁寧にする
• 寿命が短く、自明なローカル変数だけは無コメントでよい

変数コメントに書くこと

• この変数が何を表すか
• どこで使うか、後続処理でどう使うか
• 必要なら単位、範囲、基準、nullable、更新タイミング

定数ルール

• 定数は大文字スネークケース
• 単位を名前に含める
• 定数コメントには次を書く
  • 何の値か
  • 単位
  • なぜその値か
  • 外部仕様依存なら仕様名

関数ルール

• 1 関数 1 責務
• 公開関数には JSDoc / docstring を付ける
• 次を明記する
  • 目的
  • Parameters / Args
  • Returns
  • Raises
  • 副作用
  • 必要なら Note に実装理由
• 関数内部では処理のまとまりごとに要約コメントを許可する
• 行ごとの逐一説明コメントは禁止

設計ルール

• 早期リターンでネストを浅くする
• 複雑条件は説明変数に分ける
• 説明変数は、条件式や計算式の意味が一目で分かる名前にする
• 命名とコスト・副作用を一致させる
  • get は副作用なし
  • size は即時計算を期待させる
  • 重い処理は compute, calculate, count を優先する

webrtc3 で特に守ること

• useStreamReceiver.js を無秩序に肥大化させない
• DOM 直操作は既存 service へ寄せる判断を優先する
• SkyWay join / publish / subscribe / leave の順序を壊さない
• 画面共有、背景ぼかし、RNNoise の既存責務を跨いで混ぜない
• UI 修正だけの依頼で service 層まで広げない

重要な state / ref / handler のコメント厳格化

• 重要な state / ref / store / handler / callback は、グループコメントではなく 各定義直前に個別コメントを必須 とする
• 1つのコメントで複数の重要変数をまとめて説明してはならない
• 別ファイルへ切り出した場合も、元ファイルにあった重要変数コメントの密度を下げてはならない
• destructuring で受ける重要な値も、役割が自明でない場合は受け側で補足コメントを付ける
• 特に useState / ref / store / selected* / tempSelected* / show* / is* / has* / can* / should* / *Handler / *Callback は、後続の分岐・UI 制御・接続順序に関わるならコメント必須

失敗条件

• 重要な state / ref / handler / callback が、各定義直前の個別コメントなしで残る変更は不合格とする
• 1つのグループコメントで複数の重要変数をまとめた場合は不合格とする
• 別ファイルへ切り出した結果、元ファイルより重要変数コメントの密度が下がった場合は不合格とする

出力形式

1. 実装方針
2. コード
3. 変数・定数・関数コメントの意図
4. 1年後に読んでも分かるための改善点