supersovaa Explain Code Without Code
コードから得た情報を、コードを読まなくても理解できる説明へ変換する。
詳しさは維持し、説明の単位を実装上の名前ではなく、意味・役割・振る舞いに置く。
Core rule
コード上の構造より、処理の意味・目的・振る舞いを中心に説明する。
詳細な説明でも、可能な限り識別子を使わずに説明する。
識別子や実コードを示す必要がある場合は、その意味や役割も併記する。
Explanation focus
説明では、文脈に応じて次の情報を優先する。
- 何を実現しているか
- どのような入力や状態を扱うか
- どの条件で振る舞いが変わるか
- どのように状態やデータが変化するか
- どのような結果を返すか
- どのような場合に失敗するか
- その処理が必要な理由
- 他の処理や利用者から見た影響
必要な項目だけを選び、説明形式は内容に合わせる。
Identifiers
変数名、関数名、型名、クラス名などの識別子は、説明そのものの代わりではなく、実装との対応を示す補助情報として扱う。
識別子を示す場合は、同じ箇所で意味や役割が分かるようにする。
例えば、名前だけを挙げる代わりに「認証済みかを表す値」「入力を保存可能な形に整える処理」のように意味を先に説明し、必要なら対応する識別子を添える。
Showing code
実コードを示す場合も、周囲の説明は意味と役割を中心にする。
コード片を参照するときは、そのコードが何を表し、どの振る舞いに関係するかを説明する。
Reviews
コードレビュー、差分レビュー、PR の説明にもこの方針を適用する。
指摘では、実装箇所の名前だけでなく、次の内容が分かる説明を優先する。
- 何が問題になるか
- どの条件で問題が起きるか
- 利用者やシステムの振る舞いにどう影響するか
- 修正によって期待される振る舞いがどう変わるか
実装箇所を特定するために識別子を示す場合は、その箇所の役割も併記する。
Scope
このスキルは、コードを根拠として人に説明する場面全般に適用する。
対象には、実装説明、調査結果、コードレビュー、差分レビュー、PR の説明、障害原因の説明、修正内容の説明を含む。
ユーザーがコード上の名前や構造そのものを知る必要がある場面では、それらを意味や役割と対応づけて説明する。