シンプル・イングリッシュ は何をしますか？
要点を、必要最低限の平易な言葉で伝え、それ以上は語らない。読者は詳細をコードで確認する。
簡潔に
- ポイントから始める：その機能が何をするか、そしてそれが明らかでないならなぜなのか。
- コードや差分がすでに示していることは省略する：触れたファイル、手順の順序、コードが処理するエッジケースなど。
- 業界で使われるコンパクトな表現を使う：「未使用のアイコンを削除」と書くのであって、「何も使っていないアイコンを削除する」とは書かない。
- 同じ事実は一度だけ述べる。
- 言葉を削るのであって、事実を削らない。読者が問題を把握するために必要な各ステップを残し、その結果を述べる：「その日付はCIがリリースを行う日とは異なる場合がある」と書き、「見出しはリリース日前に書かれる」とは書かない。
明瞭に
簡潔は曖昧ではない。
- 一文に一つのアイデア、主語と動詞を明確に。セミコロン、なぞなぞ、スローガン（「リリースなし、タイプなし」など）は使わない。
- 主語を先頭に置き、誰が行動するかを明示する：「C++がXを計算する」と書き、「XはC++で計算される」とは書かない。
- 単純時制を使い、今も真であることには現在形を使う：「QMLはそのバインディングを再評価しない」と書き、「再評価されなかった」とは書かない。
- 条件は「もしXならば、Y」と書く。
- 名詞が節の中に戻る場合、あるいは複数の名詞が該当しうる場合、「それ」「それら」「あれら」の代わりに名詞を繰り返す。
- 「which」「whose」の節は短く保つ。その節に長い主語がある場合は、別の文にする：「DebianとUbuntuのQtパッケージにはそれが含まれていない」と書き、「それをDebianとUbuntuのQtパッケージは省いている」とは書かない。
- 否定は明確に言う：「範囲外の値は無視する」と書き、「範囲を超えた値は受け取らない」とは書かない。目的語を通じて否定しない：「編集はupdated()を発行しなかった」と書き、「編集はupdated()を発行しなかった（no）」とは書かない。「nor」は「neither」の後にのみ使う。
ネイティブらしく
テキストは、英語を母語とする開発者が書いたように読める必要がある。もしフレーズが翻訳のように読めるなら、たとえ書き換えで単語が一つ増えても、書き直す。
- 「of」の連鎖ではなく、複合名詞を使う：「アプリ設定」「CSVファイルダイアログ」「DebianとUbuntuのQtパッケージ」。複合名詞が使えない場合にのみ所有格を使う（例：「シートの密度」）。所有格を連続して使わない。フレーズごとに「of」は最大一つまで。
- 業界で通常使われる動詞を使う：「表示する」「報告する」「修正する」「サポートする」「処理する」「確認する」。コードを人に見立てて「伝える」「答える」「運ぶ」とはしない。「所有する」はC++の所有権の意味でのみ使う。
- 概念ごとに一つの言葉を使う：「確認する」か「検証する」か、「設定」か「オプション」かを選び、統一する。
- リスト内で冠詞を繰り返さない：「フレームと削除ボタン」。
- 要件には「must（しなければならない）」、可能性には「can（できる）」を使う。「should」「may」「might」は避ける。
- 「for example」と書き、「e.g.」とは書かない。アメリカ英語のスペリングを使う。
- 以下の単語は削除する：「leverage」「utilize」（「use」と書く）、「in order to」（「to」と書く）、「prior to」（「before」と書く）、「ensure」「simply」「just」「easily」「seamlessly」「robust」「powerful」「comprehensive」「functionality」「it is worth noting that」「with this change」「is designed to」「allows you to」（そのものと動詞を直接書く）、「under the hood」「out of the box」。
実際のコミット件名の改善例：
| 改善前 | 改善後 |
|---|---|
| アプリの設定をドキュメントから除外する | アプリ設定をドキュメントに保存しない |
| Graph: エクスポートに失敗したときに読者に伝える | Graph: エクスポートエラーを報告する |
| CardButtonを追加、オブジェクトのトップ行にあるアイコンボタン | CardButtonを追加、オブジェクトのトップ行にあるアイコンボタン |
| Sampler: 離散オブジェクトの値をその範囲を超えて受け取らない | Sampler: 離散オブジェクトの値を範囲外で無視する |
| リリースノートに別の日付が記載された完全リリースを停止する | 完全リリース前にリリースノートの日付を確認する |
| Ubuntu 26.04でビルド、そのQtパッケージを使用 | Ubuntu 26.04でビルド、Qtパッケージを使用 |
テキストの種類別
コミットメッセージ
- 件名は、差分がなくても意味の通る短い命令形で書く：「ドキュメントの値を設定パネルの範囲に制限する」と書き、「ドキュメントの数値をパネルの範囲内に保つ」とは書かない。
- 一つのコミットで一つのことを行う。本文に二つ目の話題が必要なら、コミットを分割する。
- 本文は、コードが今何をするか、次に短い理由を書く。
- 件名以外の事実は「also（また）」でマークする：「両方の読み取りは、新しいバージョンがキーを追加する可能性があるため、未知のキーもスキップする。」
- 読者が知っている背景情報は省略する。差分を言い直したり、変更を擁護したりしない。
コードコメント
- デフォルトでは書かない。コードが示さない理由、隠れた不変条件、または回避策のために書く。
- コードが何をするか、そこから何が導かれるか、そしてなぜか、それぞれ短い一文で述べる。コードがすでに示している部分は省略する。
- API名を明記し、比喩は使わない。命令形でよい：「同一の書き込みはスキップする：それらはまだmtimeを更新する」。
- 同僚に「なぜこれがここにあるのか？」と聞かれたときに答えるようなコメントを書く。具体的な効果を挙げる：「xminは左側に留まる」と書き、「境界はそのままの位置にある」という要約にはしない。
例：
- 改善前：
// 垂直リストはその幅を秘密にしているため、スタイルは迷子のハンドルを描画する - 改善後：
// 垂直ListViewはcontentWidthを-1のままにしており、スタイルはそれを折りたたまれたハンドルとしてレンダリングする - 改善前：
# ランナーのglibとlibsystemdはその新しいglibcを必要とするため、AppImageはホストのglibとlibdbusを使用する。linuxdeployはそれらだけが必要とするライブラリをコピーするので、リストにもそれらを記載する - 改善後：
# glib、libdbus、およびそれらの依存関係をバンドルしない。AppImageはホストのバージョンをロードする。Ubuntu 26.04のバージョンはglibc 2.43を必要としており、これは古いディストリビューションにはない。
ドキュメント
- コードが今日行うことを説明する。対象とその目的を述べ、詳細があるファイルを指し示す。
- 三つ以上の並列項目は箇条書きにする。
- スタイル、モジュール、識別子の名前はバッククォートで囲む：
FluentWinUI3。 - 変更される可能性のあるサードパーティソフトウェアに関する事実は「現在」またはバージョンを付けてマークする：「DebianとUbuntuのQtパッケージには現在それが含まれていない」。
エラーメッセージ： 何が起こったか、既知の原因、そして何をすべきか。謝罪は不要。
ツールチップ： ウィジェットが設定する内容。
エージェントへの指示： 一文に一つのルール、条件を先に。
そのまま残すもの
コード、識別子、コマンド、パス、引用されたメッセージ、製品名、ボタンやタブ、フィールド、メニューエントリの名前。
提出前に
自分が読者になったつもりでテキストを一度読む。その読者の役に立たない文はすべて削除する。残ったすべての文が初見で理解でき、通常の英語として自然に聞こえることを確認する。
チャットで同じことを説明した場合は、両方を比較する。チャットのバージョンの方が明確であれば、それを使う。