comment-and-documentation-quality

コメント、ドキュメント、コミットの品質基準

基本理念

コードコメント、ドキュメント、コミットメッセージでは、簡潔な使用方法、明白ではない制約、不可欠な 理由 を伝えてください。内部の仕組みを講義したり、リバースエンジニアリングの記録を残したり、会話調で語ったりしてはいけません。

優れた文章は、意図や明白ではない不変条件を明確にします。コード、パラメーター名、型シグネチャからすでに分かることをコメントに書くと、かえってノイズになります。コミットメッセージでは、技術的な根拠を簡潔に説明し、日記のような記述は避けてください。

---

コメントとドキュメントにおける7つのアンチパターン

1. 句読点の問題：エムダッシュ（—）、エヌダッシュ（–）、二重ハイフン（--）

• ルール： コメント、ドックストリング、技術文書、コミットメッセージで、会話調の間を表すためにエムダッシュ（—）、エヌダッシュ（–）、二重ハイフン（--）を使ってはいけません。
• 対処法： 標準的なハイフン（-）、コロン（:）、括弧を使うか、文を分けてください。
• ❌ // Set timeout — defaults to 5000ms
• ❌ * wrote -- and it really does drop writes -- so we read back
• ✅ // Set timeout (defaults to 5000ms)
• ✅ * Read back row after write to verify updates.

2. 内部の仕組みやバックエンドの小ネタの混入（README／クイックスタートの肥大化）

• ルール： 利用者向けの使用例やREADMEで、バックエンドの詳細な仕組み、レート制限の内部動作、隠れた検索コスト、運用上のトレードオフを説明してはいけません。
• 対処法： クイックスタートから完全に削除するか、簡潔なパラメーター説明1つにまとめてください。
• ❌

  // Memrise rate-limits the account and silently drops writes when it bites, so
  // each call costs a read-back. Trim the requests when that matters: numeric
  // keys need no name lookup, poolId saves the one that finds the thing's pool,
  // and verify: false drops the read-back (and with it any proof it worked).
  

• ✅

  Pass `verify: false` to skip write verification on high-volume updates.
  

3. ブール値の説明過多と大げさな論評

• ルール： ブール値オプションについて、true と false の両方の状態やデフォルト値の理由を説明したり、外部APIの動作を大げさに論じたりする複数文の説明を書いてはいけません（「何も言わないAPIを信頼する」など）。
• 対処法： フラグが制御する内容を1文で述べ、標準の @default タグを付けてください。
• ❌

  /**
   * Read the row back and confirm the new values are there. On by default,
   * because the endpoint reports the same thing whether or not it wrote.
   * Turning it off saves one request per call and trusts a silent API.
   */
  verify?: boolean;
  

• ✅

  /**
   * Whether to read back and verify updated row data.
   * @default true
   */
  verify?: boolean;
  

4. エンベロープや型変換に関する余計な説明

• ルール： ドックストリングで、1行のJSONのアンラップ、プロパティの除去、データ形状の変換を正当化してはいけません（たとえば、エンベロープキーを削除した理由を説明するなど）。
• 対処法： 関数が何を返すかを記述してください。スキーマはTypeScriptの戻り値の型で定義されます。
• ❌

  /**
   * The signed-in account, as `/v1.25/me/` reports it.
   *
   * The wrapping `profile` key is dropped, since the response carries
   * nothing else.
   */
  async getMe(): Promise<Profile>
  

• ✅

  /**
   * Fetches the current signed-in user profile.
   */
  async getMe(): Promise<Profile>
  

5. 来歴にまつわる記述とリバースエンジニアリングの日誌

• ルール： 型をどのようにリバースエンジニアリングしたか、エンドポイントのスキーマをどう見つけたか、オープンなインデックスシグネチャがなぜ存在するかを説明するメモを残してはいけません。
• 対処法： 型が何を表すかを記述し、どのように見つけたかは記述しないでください。
• ❌

  /**
   * The signed-in account. Fields below were observed on a live response; the
   * index signature covers the rest, since this payload carries whichever
   * subscription and entitlement flags the web client happens to need.
   */
  export interface Profile { ... }
  

• ✅

  /**
   * Signed-in user profile.
   */
  export interface Profile { ... }
  

6. 痕跡だけのコメントと墓標（「削除したもの」）

• ルール： 以前のコードの動作、リファクタリングの内容、不要になったものを説明するコメントを残してはいけません。
• 対処法： 完全に削除してください。過去の状態はバージョン管理の履歴で追跡できます。
• ❌ // We no longer call legacyValidate() here since v2 handles it in middleware
• ❌ // Removed old API endpoint because it's deprecated
• ✅ (コメントなし)

7. 同語反復のコメントと手順の逐次説明

• ルール： 自明なコードの内容を英語で言い換えたり、基本的な処理手順を逐一説明したりしてはいけません。
• 対処法： 完全に削除してください。
• ❌ // set loading state to false above setLoading(false)
• ❌ // Step 1: Initialize list / // Step 2: Filter items
• ✅ (コメントなし)

---

コミットメッセージ

コミットメッセージを監査する場合は、基準、アンチパターン、指摘事項のテンプレートが記載されたcommit-messages.mdを確認してください。コミットを作成または修正する場合は、利用可能であれば git-commit-quality を使い、リポジトリのコミット規約に従ってください。

残すべき正当なコメント

次の項目は必ず残してください。

1. 明白ではないドメインロジック： ビジネスルール、特殊ケースの計算、タイミングに関する不変条件。
2. 上流のバグに対する回避策： プラットフォームやブラウザーの特異な動作。特に問題のURLがある場合。
3. 公開APIの契約： 標準的な @param、@returns、@throws のドキュメント。
4. 対応可能な注記： 意図的に記載された TODO:、FIXME:、セキュリティに関する注意事項。

---

標準監査指摘テンプレート

コード、docstring、またはコミットメッセージを監査する際は、指摘を次の形式で記述します。

コードとドキュメントの場合：

### `path/to/file.ts:L42` — `<context/symbol name>`
- **Original:** `<exact original comment or docstring text>`
- **Anti-Pattern:** `<Anti-Pattern Name(s)>`
- **Issue:** `<1-sentence concise explanation of what makes it noise/bloat>`
- **Replacement:** `<Clean drop-in replacement, or *(Delete entirely)*>`