code-prose-writing

name	code-prose-writing
description	コード内のコメント、TODO コメント、テストケース名、コミットメッセージの文章規範。書く内容の取捨選択（ドメインの言葉による方針、過剰な why の抑制、経緯と指示の排除）と、文の型・語彙の制限（「〜すれば〜できる」構文、直訳調、擬人法、比喩、誇張、攻撃的な語、括弧による強調、接続詞の省略、並列でない箇条書きの禁止）を定める。コメントを書くとき、テスト名を付けるとき、コミットメッセージを作るとき、およびそれらを推敲するときに使用する。

コメント・テスト名・コミットメッセージの文章規範

コメント、テストケース名、コミットメッセージを書く・直すときは、以下に従う。 記述する言語は周囲の記述に合わせる。直訳調の禁止は日本語で書く場合に適用し、それ以外の規範は言語を問わず適用する。 英語で書く場合、無生物を主語に置く形（The service retries failed calls.）は擬人法にあたらない。接続詞の規範は、文頭に関係を示す語を置く形（Instead, Because ...）と、等位接続詞で一文にまとめる形のどちらでも満たす。 一つの記述に複数の規範がかかり、両立しないときは、ドメインの言葉で書くほうを選ぶ。ただし、言い換えた結果、何が起きるのかが読み取れなくなる場合は、読み取れる書き方を選ぶ。 規範が、依頼された変更の範囲の外にまで及ぶときは、範囲の外は直さない。該当する箇所を報告するにとどめる。範囲は記述の種別で数える。テスト名の付け直しを依頼されたなら、隣にあるコメントは範囲の外である。

何を書くか

• ドメインの言葉で方針を書く。実装手段の説明は、方針だけでは読めない箇所に限る。
  • 悪い例：// 注文を Map に詰め替えて O(1) で引けるようにする
  • 良い例：// 同一の顧客からの注文はまとめて 1 件として扱う
• why は必要な分だけ書く。コードを読めばわかる理由、一般的な設計上の常識、背景の説明を並べない。理由を書くのは、コードの見た目に反する判断をしている箇所に限り、一文で足りることが多い。
  • 悪い例：// 可読性と保守性を高めるため、責務を分割している。これにより変更時の影響範囲が限定され、テストも書きやすくなる
  • 良い例：// 締め日をまたぐ注文は前月分として集計する
• 変更の経緯を書かない。以前の実装、修正の履歴、途中で試した方法は、コメントとテスト名に残さない。コミットメッセージだけは例外とする。
  • 悪い例：// もともとは同期処理だったが、非同期に変更した
  • 良い例：// 集計の完了を待たずに応答を返す
• 指示や指摘を書かない。会話やレビューの内容を知っている前提の記述も書かない。読み手はコードだけを見ている。
  • 悪い例：// 指摘のとおり、ここではバリデーションを行わない
  • 良い例：// 入力の検証は呼び出し元で済んでいる

文の型

• 「〜すれば〜できる」の構文を使わない。条件と効果の説明ではなく、対象が何であるか、何をするかを書く。
  • 悪い例：// このフラグを立てれば、キャッシュを無効化できる
  • 良い例：// キャッシュを使わずに毎回取得するフラグ
• 接続詞を省略しない。二文以上を並べるときは、文と文の関係がわかる語を文頭に置く。接続詞を補って文が増えるときは、先に文をまとめて数を減らし、そのうえで残った文に接続詞を置く。
  • 悪い例：// 再試行はしない。呼び出し元が失敗を扱う
  • 良い例：// 呼び出し元が失敗を扱う。そのため、ここでは再試行しない
• 並列でない内容を箇条書きにしない。前提、手順、注意のように役割の違うものを並べるときは、文でつなげて書く。
• 括弧による強調を多用しない。「」は引用と、誤読を招く語の明示に限る。
  • 悪い例：// ここでは「正規化」した「値」を「一時的に」保持する
  • 良い例：// 正規化した値を、書き込みが終わるまで保持する
• 平凡な文にする。読ませる工夫や言い回しの工夫を加えない。

語彙

• 英語の比喩的な名詞をカタカナのまま持ち込まない。ゲート、ガードレール、ハンドオフ、パイプライン、ソースオブトゥルースのような語は、日本語では何を指すのかが伝わらない。何をする箇所なのかを普通の言葉で書く。
  • 悪い例：// 保存前の品質ゲート
  • 良い例：// 保存する前に、必須の項目が入力されているか確認する
  • 悪い例：// 集計処理へのハンドオフ
  • 良い例：// ここから先の計算は集計処理で行う
  • 悪い例：// 設定のシングルソースオブトゥルース
  • 良い例：// 設定の値はこのファイルだけに書く
• 英語の構文をなぞった言い回しを使わない。「〜を可能にする」「〜に責任を持つ」「〜を提供する」のような形は、動詞をそのまま日本語に置き換えたために不自然になっている。主語と動詞を日本語の並びで書き直す。
  • 悪い例：// 呼び出し元が独自の書式を指定することを可能にする
  • 良い例：// 呼び出し元で書式を指定できる
  • 悪い例：// このクラスは在庫数の整合性に責任を持つ
  • 良い例：// 在庫数の整合性はこのクラスで保つ
• 擬人法を使わない。コード、クラス、サービスを、意思や感情を持つものとして書かない。
  • 悪い例：// このクラスは在庫の状態を知っている
  • 良い例：// このクラスが在庫の状態を保持する
• 比喩を使わない。対象をそのまま指す語で書く。日常的に使われていて気付きにくい比喩も同じく避ける。
  • 悪い例：// リクエストの門番として働く
  • 良い例：// 権限のないリクエストをここで止める
  • 悪い例：// 必須の項目が埋まっているか確認する
  • 良い例：// 必須の項目が入力されているか確認する
• 誇張した表現、物語のような表現を使わない。
  • 悪い例：// 劇的に性能を改善する魔法のようなキャッシュ
  • 良い例：// 同じ問い合わせの結果を再利用する
• 強すぎる言葉と攻撃的な表現を使わない。禁止や警告を伝えるときも、何をすればよいかを事実として書く。
  • 悪い例：// 絶対に触るな。壊れるぞ
  • 良い例：// 値を変えるときは、集計側の丸め処理も合わせて直す

コメント

• コメントは、名前と引数だけでは読み取れない前提、制約、判断がある箇所に付ける。名前から読み取れることを言い直すだけの箇所には付けない。
• コードをそのまま日本語に置き換えただけのコメントを書かない。コードに定数や引数として現れている値も、コメントで繰り返さない。
• 既にあるコメントの推敲を依頼されたときは、書き直しに加えて、名前から読み取れることを言い直すだけのコメントを消す。
• 関数やクラスに説明を付けるのは、名前と引数から読み取れない前提や制約があるときに限る。付けるときは、何をするものかを先に書き、制約や例外的な扱いをそのあとに続ける。
• コメントは、判断が 1 行に現れる場合はその行の直前に置く。判断が複数行にまたがる場合は、その先頭の行の直前に置く。
• 仮実装として残す箇所には // TODO: を付け、そのあとに、本来どうするべきかを書く。書き方はほかのコメントと同じで、ドメインの言葉で方針を書き、経緯や指示には触れない。
  • 悪い例：// TODO: あとで直す
  • 悪い例：// TODO: 指摘のあったレートの扱いを直す
  • 良い例：// TODO: 為替レートは固定値ではなく、注文日のレートで計算する
• 仮実装ではない箇所に TODO を付けない。一時的なメモ、作業中の覚書、自分への問いかけも残さない。

テストケース名

• 条件と期待する結果を書く。「〜のとき、〜する」「〜の場合、〜を返す」のような形にする。これらは例示であり、条件と結果の両方が読み取れるなら別の形でもよい。
  • 悪い例：金額を指定すれば合計が計算できる
  • 良い例：注文が複数あるとき、金額の合計を返す
• 条件と期待する結果の両方をドメインの言葉で書く。内部の実装名や型名で表さない。検証に使う関数に由来する言い方（例外を投げる、エラーにならない など）も、業務の上で何が起きるかに言い換える。
• 条件には、テストに渡す引数の形ではなく、その引数が業務の上で表しているものを書く。
• 例外を投げないこと、値が空でないことのように、何が起きないかだけを確かめるテストでは、その検証が通ったときに業務の上で成り立っている状態を書く。
  • 悪い例：顧客が休止中のとき、エラーにならない
  • 良い例：顧客が休止中のときも、請求額を計算する
  • 悪い例：orderList が空配列のとき、例外を投げる
  • 良い例：注文が 1 件もないとき、集計を拒否する
• 修正の経緯を名前に含めない。
  • 悪い例：リグレッション：以前落ちていた締め日の計算
  • 良い例：締め日をまたぐ注文は、前月分として集計する
• 「正しく動く」「正常に処理される」のように、何を確かめるのかがわからない名前にしない。

コミットメッセージ

• 既存の履歴の形式に合わせる。接頭辞の有無、記述の言語、件名の書き方を揃える。
• 接頭辞を使う履歴では、種類を変更の目的で選ぶ。利用者から見た不具合が解消される変更は fix、外から見た振る舞いが変わらない整理は refactor とする。範囲を表す語は、既存の履歴で同じ領域に使われているものに合わせる。
• 件名には、この変更が何をするものかを書く。効果や可能になることではなく、変更そのものを書く。
  • 悪い例：設定を変えれば言語ごとの起動が速くなるようにした
  • 良い例：disable language runtime support in neovim
• 本文は必要なときだけ書く。件名だけでは判断の理由がわからない場合に、数文で書く。
• 本文に書くのは判断の理由と以前の状態に限る。変更したファイルの一覧や、付随して直したテストのような差分の内訳は書かない。
• 変更の経緯を書いてよい。以前の状態、その状態で起きていたこと、変更後の状態の順に書く。
• 指示や指摘は書かない。依頼を受けたこと、レビューでの指摘、会話の流れには触れず、変更の内容と理由だけを書く。
  • 悪い例：レビューでの指摘に対応して、リトライ処理を削除した
  • 良い例：リトライ処理を削除する。呼び出し元でも再試行しており、同じ要求が二重に送られていた

書いたあとの点検

書き上げたら、次を順に確認する。

• 「〜すれば〜できる」の形が残っていないか。
• 以前の実装や修正の経緯に触れていないか。コミットメッセージ以外では残さない。
• 会話やレビューを知らない読み手が、そのまま読めるか。
• 理由の説明が、判断の要点を超えて続いていないか。
• 実装手段の説明が先にあり、ドメインの言葉による方針が後回しになっていないか。
• 英語の比喩をカタカナにした語、英語の構文をなぞった言い回し、擬人法、比喩、誇張、強すぎる語が混じっていないか。
• 「」による強調が並んでいないか。
• 箇条書きの各項目が、同じ役割の並列になっているか。
• テスト名と、その近くのコメントが同じ内容を述べていないか。同じなら名前に残し、コメントは名前から読み取れない事情に限る。
• 二文以上あるとき、文と文の関係を示す語が文頭に置かれているか。