conventional-comments

Conventional Comments

Conventional Comments 標準に基づいています。理解しやすく、検索しやすいコメントです。

コメントの形式

<label> [decorations]: <subject>

[discussion]

• label（必須）— コメントの種類を示す単語
• subject（必須）— コメントの主なメッセージ
• decorations（任意）— ラベルの後に置く、括弧で囲んだ追加の分類子（カンマ区切り）
• discussion（任意）— 補足説明、背景、理由、次のステップ

ラベル

すべてのコメントの先頭に、次のラベルを付けます。

ラベル	目的
praise	良い点を取り上げます。レビューごとに少なくとも1つ残してください。誠実である必要があります。うわべだけの称賛は逆効果です。
nitpick	好みに基づく些細なリクエストです。性質上、ブロッキングではありません。
suggestion	改善案を提案します。何を、なぜ改善するのかを明確にしてください。
issue	具体的な問題（ユーザー向け、または内部的な問題）を指摘します。可能であれば提案も添えてください。
todo	小さく些細ですが、必要な変更です。issue や suggestion より簡潔に記述できます。
question	懸念の可能性はあるものの、確信が持てない場合に使います。確認や調査を依頼してください。
thought	レビュー中に浮かんだアイデアです。ブロッキングではありませんが、指導や焦点を絞った取り組みに役立ちます。
chore	承認前に完了させる必要があるタスクです。可能であれば、プロセスの説明へのリンクを付けてください。
note	常にブロッキングではありません。読み手が知っておくべきことを伝えます。

任意の表現ラベル：

ラベル	目的
typo	todo と同様ですが、誤字の問題に使います。
polish	suggestion と同様ですが、問題はなく、すぐに実施できる品質改善に使います。
quibble	表現を和らげた nitpick です。

装飾

装飾は、ラベルの後に括弧で囲んで追加し、背景情報を補足します。

装飾	意味
(non-blocking)	承認を妨げてはなりません。コメントが既定でブロッキングとなる場合に役立ちます。
(blocking)	承認前に必ず解決する必要があります。コメントが既定でブロッキングではない場合に役立ちます。
(if-minor)	修正が軽微または些細な場合にのみ解決します。

コメントをさらに分類するため、独自の装飾（例：security、ux、test、performance）を追加してもかまいません。最小限にとどめてください。装飾が多すぎると読みやすさが損なわれます。

コードレビューの書式

すべてのコメント出力は、有効な GitHub Flavored Markdown でなければなりません。PR のコメントにそのままコピー＆ペーストされることを想定してください。

コード参照

コメントを配置する場所以外の場所を読者に示す場合（例：別のファイルにある関連コード、共有ユーティリティ、更新が必要なテスト）に限り、ファイルパスや行番号を明示してください。それ以外の場合、位置情報は GitHub のレビュー UI によって処理されます。

コメント内のコード

• インラインコード（変数名、関数呼び出し、値）は、単一のバッククォートで囲みます：`myFunction()`
• 複数行のコードスニペットには、言語タグを付けたフェンス付きコードブロックを使用します。

```python
def example():
    return True
```

• 置き換えを提案する場合は、現在のコードと提案するコードの両方をフェンス付きブロックで示します。

コミュニケーションのベストプラクティス

好奇心を持つ

すべての背景情報を把握しているとは限らないと考えてください。結論を事実として述べるのではなく、質問してください。

• 悪い例："Main コンポーネントでこのバグを修正できます。それならコードもかなり少なく済むでしょう。"
• 良い例：question: "Main コンポーネントで修正できるでしょうか。より単純な修正になり、コードも少なくて済むのではないかと思います。"

「あなた」ではなく「私たち」を使う

文章によるレビューでは、声のトーンが伝わりません。「あなたは〜すべきです」は、相手を責めるように感じられます。協力的な表現にしましょう。

• 悪い例：issue: "テストを書くべきです。"
• 良い例：todo: "テストを書く必要があります。"

実行可能なコメントを残す

コメントへの対応方法が明確になるようにしてください。明確な進め方がない場合は、そのことが伝わるようにしてください。

類似するコメントをまとめる

細かなコメントをたくさん付けるのではなく、類似する問題はまとめて指摘してください。役立つ場合は、パッチや例を含めてください。

患者的なメンタリング

忍耐強く親切に共有された知識は、より深く伝わり、今後のレビューにも広がっていきます。

例

称賛：

praise: テストカバレッジが素晴らしいです。エッジケースもよく考慮されています。

コードを添えた提案：

suggestion (security): ここで独自の DOM サニタイズ関数を実装している点が少し気になります。

代わりに、フレームワーク組み込みのサニタイザーを使うことを検討できませんか？

// Instead of
function sanitize(input: string) { ... }

// Use
import { sanitize } from '@angular/core';

補足付きの問題点：

issue (ux, non-blocking): これらのボタンは赤にするべきですが、その対応は後続の作業にしましょう。

補足付きの質問：

question (non-blocking): この時点では、どのスレッドが勝ったかは重要でしょうか？

競合状態を防ぐために、すべてのスレッドが勝つまでループし続けるべきかもしれません。

細かな指摘：

nitpick: little star => little bat

ほかの箇所の表記も更新できますか？

別ファイルへの参照（異なる場所を示す場合）：

suggestion: この検証処理は、src/utils/validate.ts#L30-L45 のロジックと重複しています。代わりに、ここで validateInput() を再利用できませんか？

作業依頼：

chore: 既知の参照先に影響がないことを確認するため、lint-check CI ジョブを実行しましょう。

このジョブの実行方法についてはこちらのドキュメントをご覧ください。サポートが必要な場合は、お気軽にご連絡ください。

提案をまとめる場合（類似のフィードバックをまとめる）：

polish: すべての m_X 変数を X に変更できますか？このプロジェクトではハンガリアン記法を使用していません。

たとえば：

// Instead of
interface Wizard { m_foo: string; }

// Use
interface Wizard { foo: string; }