Skip to content

Instantly share code, notes, and snippets.

@masakielastic

masakielastic/rfc-style2.md

Last active March 23, 2026 07:41
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save masakielastic/14372971e3a3873625edbd966b1842a2 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save masakielastic/14372971e3a3873625edbd966b1842a2 to your computer and use it in GitHub Desktop.
Download ZIP
PHP RFC のためのレビュー。改訂版
Raw
rfc-style2.md

PHP RFC の英文レビューと改稿を手伝ってください。対象は UTF-8 の code-point traversal を扱う str_iter() RFC です。レビュー方針と文章スタイルは次のとおりです。

目的

  • 小規模 RFC として、論点を増やしすぎず、仕様の境界を明確にする
  • 「なぜ追加する必要があるのか」「誰にとって意味があるのか」を重視する
  • 便利機能の寄せ集めではなく、shared primitive / building block という位置づけを明確にする
  • validation や grapheme cluster のような隣接論点とは意図的に切り分ける

議論のスタイル

  • まず節ごとの役割を明確にしてください
    • Introduction は位置づけ
    • Proposal は仕様
    • Survey は観察
    • Motivation は問題設定と必要性
    • Design Rationale は設計判断の理由
    • Future Scope は今回扱わない隣接論点
  • 「この内容は Survey ではなく Rationale に置くべき」のように、節の役割に基づいて整理してください
  • 論点が重複している場合は統合案を示してください
  • 藁人形論法っぽい表現、過剰な一般化、曖昧な大風呂敷表現を避けてください
  • 抽象論だけでなく、「何を残し、何を削るべきか」を具体的に示してください
  • 可能なら、そのまま貼れる英文案も示してください

文章の書き方

  • RFC らしく、簡潔で落ち着いた英語にしてください
  • 強すぎる断定や煽りは避けてください
  • ただし、設計判断は曖昧にせず、責務分離やスコープ制限は明確にしてください
  • “Unicode handling as a whole” のような曖昧で大きすぎる表現は避けてください
  • “higher-level text APIs” のような焦点のぼやける表現は避け、必要なら validation / grapheme handling / substring / length など具体化してください
  • Survey では著者の意見を混ぜすぎず、観察に寄せてください
  • Motivation や Design Rationale では、Survey の観察からどんな設計判断を導くのかを述べてください
  • “primitive” は「複数の高レベル挙動の building block になる小さな共有基盤」という意味で扱ってください

この RFC の設計方針

  • str_iter() は UTF-8 code-point traversal を提供する shared primitive
  • mbstring 専用 API ではなく、core の shared primitive として位置づけたい
  • code point traversal を扱い、validation policy や grapheme cluster handling は別論点として切り離す
  • invalid UTF-8 に対しては validation や error reporting を行わず、forward progress のみを保証する
  • 「観測」と「対応」は分けて考える
  • 基盤機能は policy を薄く保ち、アプリやフレームワーク側で文脈付きの error handling を決める、という整理を重視する
  • iterator-based API を先に定義する理由として、traversal は sequential iteration として自然であり、substring / length は indexing, offsets, argument behavior, compatibility など別の仕様判断を多く含むことを重視する

これまでに固まっている方向性

  • Introduction では validation / grapheme handling までに留め、normalization / transliteration には触れすぎない
  • Proposal ではサンプルコードを早めに示し、「コードを見てわかること」と「仕様文で固定すべきこと」を分ける
  • サンプル文字列は héllo🙂 のように、ASCII / 非 ASCII / emoji の違いが見えるものを好む
  • iterator_count() の例は補助例にはなりうるが、主サンプルにはしない
  • Design Rationale の主要 FAQ は次の4本を中心に考える
    1. Why define traversal as an iterator-based API?
    2. Why introduce str_iter() in core rather than mb_iter() in mbstring?
    3. Why does this RFC leave validation behavior unspecified for ill-formed UTF-8?
    4. Why does this RFC iterate over code points rather than grapheme clusters?
  • Future Scope では validation primitives / grapheme cluster support / 必要なら length and substring APIs を扱う

回答のしかた

  • まず総評を短く述べる
  • その後、節ごとに「どこがよいか」「何を直すべきか」を示す
  • 必要なら改善案をそのまま使える英語文として提示する
  • 可能なら「第一候補」「やや強め」「やや事務的」のように複数案を出す
  • RFC の政治性や説得力も意識しつつ、過度に雄弁にはしない
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment