PHP RFC の書き方・議論スタイル共有メモ

概要

このメモは、今回の FILTER_VALIDATE_STRLEN RFC 検討を通じて整理した、PHP RFC の書き方と議論の進め方の実践メモである。目的は、他のチャットや今後の RFC 作成で再利用できる形で、論点設定・文章構成・FAQ 設計・スコープ管理の勘所を共有することにある。

1. PHP RFC は「仕様書」だけではなく「公開討論のための設計文書」

PHP RFC は、単に機能仕様を列挙する文書ではない。

何を追加するか
なぜその形なのか
どこまでを扱い、どこから先を扱わないのか
反対意見が出るとしたら何か

を、投票前に共有するための文書である。

つまり RFC は、実装説明書というより、設計判断を可視化する公開文書として書く必要がある。

2. 小さな RFC では Proposal 主導にする

今回のような小規模 RFC では、Introduction / Motivation / Proposal / Specification をすべて厚く書くと冗長になりやすい。

そのため、構成の基本方針は次のようになる。

Introduction: 必要なら論点設定だけ
Proposal: 仕様の中心
FAQ: 設計判断の補助
Backward Incompatible Changes: 簡潔に
Future Scope / Open Question: 未解決領域の切り分け

特に重要なのは、Proposal を読めば仕様の骨格が分かる状態にすることである。

Proposal に書くべきこと

何を追加するか
何を測るか / 何を判定するか
どの条件で success か
option の妥当条件
return semantics
この RFC が意図的に扱わない範囲の最小限の宣言

Proposal に書きすぎないほうがよいこと

一般的な入門説明
長い背景説明
FAQ で扱うべき設計比較
future scope の議論

3. Introduction は「追加内容」ではなく「争点設定」に寄せる

Introduction と Proposal の両方で「This RFC proposes adding ...」を書くと冗長になりやすい。

そのため、Introduction を置く場合は、追加内容ではなくこの RFC が何を争点としているかを書く。

例:

This RFC treats code-point length validation as part of PHP’s built-in validation baseline rather than as a specialized text-processing feature.

このようにすると、

Introduction = 立場・位置づけ
Proposal = 具体仕様

という役割分担ができる。

Introduction が不要なら、省略して Proposal から始めてもよい。

4. FAQ は「初心者向け解説」ではなく「想定反論への短い応答集」

今回もっとも有効だったのは、FAQ を長い説明集ではなく、記者会見の想定問答として使う考え方である。

FAQ の目的は、知識伝達そのものよりも、次の点にある。

読者が気にする論点を先回りして明示する
設計判断を短く説明する
スコープ・クリープを防ぐ
「ここまでは答える」「ここから先は open question」と線引きする

FAQ の書き方の型

質問: 実際にレビューで出そうな問い
1 行目: 短い設計根拠
2〜3 行目: 補足説明

例:

Why not reuse min_range and max_range?
min_len and max_len make the option semantics specific to string length.

min_range and max_range are associated with numeric validation in filter. Using length-specific names keeps the constraint explicit and avoids reusing numeric range terminology for a different validation model.

この型を守ると、FAQ が長文化しにくく、上級者向けのトーンを維持しやすい。

5. FAQ は「論点の順番」が重要

FAQ は単なる寄せ集めではなく、読み順で意味が変わる。

今回のような RFC では、次の順番が自然だった。

Why this feature?（位置づけ）
Why this scope?（適用範囲）
Why this model?（設計モデル）
Why this API?（命名・表面設計）
Why this boundary?（境界値）
Why not more?（今回扱わないもの）
Open question（未解決問題）

この順番にすると、FAQ 全体が「提案の防衛線」ではなく、「設計判断の地図」として読める。

6. スコープ・クリープを防ぐ言い方を選ぶ

RFC では、何かを採用しない理由を書くときに、つい対象を弱く評価しすぎることがある。

例:

grapheme clusters は baseline validation に向かない
multi-encoding は複雑すぎる

こうした書き方は、不要な対立や誤読を生みやすい。

今回学んだのは、否定ではなくスコープ管理として書くことの重要性である。

悪い書き方になりやすい例

X is not suitable for validation.
Y is better suited for presentation only.

より安全な書き方

X raises additional boundary and API design questions, so this RFC keeps the scope limited to ...
Supporting Y would broaden the design space beyond the scope of this RFC.
This RFC does not address that question.

つまり、

相手を否定しない
将来可能性を閉じない
今回扱わない理由をスコープ管理として説明する

のが重要である。

7. Open Question は「敗北」ではなく誠実な切り分け

RFC では、未解決の設計問題を無理に解決しようとすると、提案全体が重くなる。

そのため、別問題を open question として残すのは弱さではない。むしろ、スコープを保ちながら誠実に議論を進めるための技法である。

例:

Is a UTF-8 encoding validator needed?

この問いを最後に置くことで、

今回の RFC はそこを決めない
しかし問題の存在は認識している
将来議論の余地はある

という姿勢を自然に示せる。

8. Backward Incompatible Changes は役割を守って短く書く

この節では「何を追加するか」を繰り返さない。

ここで答えるべきことはただ一つで、既存コードが壊れるかどうかである。

小さな追加 RFC なら、次のように短くてよい。

None.

または必要なら 1 文だけ足す。

None. This RFC adds a new validation filter and does not change the behavior of existing filters.

9. 例は 1 つでよいが、中心論点を黙って示せるものを選ぶ

Proposal のコード例は、複数並べるより 1 つだけのほうが締まりやすい。

その代わり、その 1 例で中心論点が見える必要がある。

今回のような RFC なら、

非 ASCII を含む
code point を意識させる
bounds の意味が分かる

例が向いている。

例:

filter_var("hello😀", FILTER_VALIDATE_STRLEN, [
    "options" => [
        "min_len" => 6,
        "max_len" => 6,
    ],
]);

この種の例は、byte length ではなく code-point length を測っていることを、説明しすぎずに示せる。

10. invalid UTF-8 の具体例は Proposal ではなく FAQ か実装側へ

This filter performs length validation only. It does not validate whether the input is well-formed UTF-8.

の後に、"hello😀\x80" のような invalid input の例を置きたくなることがある。

しかしこれは Proposal では重すぎることが多い。理由は、読者の注意が仕様本体ではなく invalid input の細部へ移りやすいからである。

そのため、

Proposal: 境界だけ宣言する
FAQ: 設計意図を補足する
実装 PR / tests: 具体例を示す

という切り分けのほうがよい。

11. 今回の実践で有効だった判断基準

文章判断

同じことを 2 回言っていないか
Proposal が FAQ に依存しすぎていないか
FAQ が長い解説になっていないか
open question を無理に閉じていないか

設計判断

これは仕様か、FAQ か
これは今回決めることか、将来課題か
これは相手の案を否定しているのか、今回扱わないだけか
これは防衛線か、論点整理か

12. 他の RFC にも流用できるテンプレート

Introduction

論点設定だけを書く
追加内容の宣言は Proposal に譲る

Proposal

追加内容
判定対象
成功条件
option ルール
return semantics
scope boundary

FAQ

Why this feature?
Why this scope?
Why this model?
Why this API?
Why this boundary?
Why not more?
Open question

BIC

None. でよいなら短く済ませる

13. まとめ

今回の学びを一言で言うと、PHP RFC は「全部説明する文書」ではなく、設計判断を適切な密度で並べる文書だということである。

Proposal は仕様の骨格
FAQ は論点整理
Open question は誠実な切り分け
スコープ管理は否定ではなく境界設定として書く

この方針を守ると、小さな RFC でも密度が高く、議論しやすい文書になる。

masakielastic/php_rfc_style.md

Select an option

No results found