| name | prune-for-readers |
| description | ドキュメントやコードコメントから、読者にとって価値の無い記述を取り除いて最終状態だけにする。作業の過程・暫定の注記・自明な説明が残っているときに使う。 |
| disable-model-invocation | true |
Prune for Readers
入力
$ARGUMENTS
対象が指定されていればそれを、無ければ直近の変更で書いたドキュメントとコードコメントを対象にする。
原則
永続テキストはこれから読む人のためにある。書いた人の作業過程を記録する場所ではない。
判定は 1 つ。その記述が、今後この文書を読む人の判断を変えるか。
変えないなら落とす。書いた時点では意味があった情報でも、読む時点で価値が無いなら残さない。
落とすもの
| 種類 | 例 |
|---|
| 作業の過程 | 試して変えた選択肢、検討して却下した案、命名や設定値の変遷 |
| 時点に依存する注記 | 「暫定的に」「今のところ」「将来的には」「一旦」 |
| コードを読めば分かること | 処理の逐語訳、変数名の言い換え |
| 文書の自己言及 | 「このセクションでは〜を説明する」「以下に示す」 |
| 一般論 | その場に固有でない、どこにでも書ける説明 |
残すもの
| 種類 | 例 |
|---|
| 判断の根拠 | なぜこの設計か。他の選択肢が今も有効な場合はその対比を含む |
| 知らないと踏む地雷 | 素直な実装が壊れる理由、ライブラリの落とし穴 |
| 外部制約 | 仕様・API・法令など、コードからは読み取れない縛り |
| 意図的な逸脱 | 通常と違うことをしている理由 |
判断に迷う記述は、それを消したとき読者が困るかで決める。困らないなら落とす。
対象外
| 対象 | 理由 |
|---|
| ADR・Design Doc | 意思決定の記録が目的 |
| commit message・PR 本文 | 変更を述べるのが役割 |
| CHANGELOG | 履歴そのもの |
手順
- 対象のドキュメント・コメントを読む
- 各記述を上の判定にかけ、落とすものを挙げる
- 書き換える。理由を述べる必要があるなら、選んだものの性質で説明する
- 判断が割れるものは書き換えず、ユーザーに提示する