========================================================================
コードコメント・ドキュメント規則 (Code Comment & Documentation Guide)
========================================================================


1. 基本方針 (Basic Policy)
------------------------------------------------------------------------
コードの可読性と保守性を高めるため，ファイル・クラス・メソッド・定数それ
ぞれに対して適切な粒度でコメントを記述する．
※ コードの書き方自体の規則は `GUIDE_04_コーディング規則.txt` を参照する．

・言語: 日本語で記述する．
・句読点: 「，」（全角カンマ）を使用し，文末の句点（「．」「。」）は付けない．
    - 列挙が続く場合は「，」で区切る．
・文体: 体言止め，または「〜する」形で統一する．
・更新: コードを変更した場合は，対応するコメントも必ず合わせて更新する．
    - コードと乖離したコメントは誤解を招くため，古いまま放置しない．


2. コメントの種類と用途 (Comment Types)
------------------------------------------------------------------------

2-1. XML ドキュメントコメント (XML Doc Comment)
    ・全ての public / protected メソッド・プロパティ・クラスに必ず記述する．
    ・トリプルスラッシュ（`///`）を使用する．

    ■ クラス・構造体
    ・書式:

        /// <summary>
        /// [そのクラスが何を表すかを端的に説明]
        /// </summary>
        internal class ClassName { ... }

    ・例:

        /// <summary>
        /// カメラの基底クラス
        /// </summary>
        internal abstract class CameraBase { ... }

    ■ メソッド（引数・戻り値あり）
    ・書式:

        /// <summary>
        /// [その処理を端的に説明]
        /// </summary>
        /// <param name="[引数名]">[説明]</param>
        /// <returns>[戻り値の説明]</returns>
        public ReturnType MethodName(Type argName) { ... }

    ・例:

        /// <summary>
        /// CSV ファイルから Mat を読み込む
        /// </summary>
        /// <param name="csvFile">読み込む CSV ファイルパス</param>
        /// <returns>読み込んだ Mat，失敗時は null</returns>
        private Mat LoadMatFromCsv(string csvFile) { ... }

    ■ メソッド（引数・戻り値なし，または自明）
    ・1行で記述してよい．

        /// <summary>
        /// 全モーターを停止する
        /// </summary>
        public void Stop() { ... }

    ■ 例外をスローする可能性がある場合
    ・`<exception>` タグを追加する．

        /// <summary>
        /// 設定ファイルから float 値を取得する
        /// </summary>
        /// <param name="param">設定キー（例: "Calib/UpdateRate"）</param>
        /// <returns>float 値</returns>
        /// <exception cref="ArgumentException">
        ///     指定されたキーが存在しない場合
        /// </exception>
        public static float GetFloat(string param) { ... }

    ■ 廃止予定のメンバー
    ・`<remarks>` タグで代替メンバーを案内し，`[Obsolete]` 属性を付ける．

        /// <summary>
        /// 画像を保存する
        /// </summary>
        /// <remarks>非推奨: SaveImageAsync を使用すること</remarks>
        [Obsolete("SaveImageAsync を使用してください")]
        public void SaveImage() { ... }

    ■ オーバーライドしたメンバー
    ・基底クラスの doc comment を継承する場合は `<inheritdoc/>` を使用する．
    ・改めて説明を書く場合はオーバーライド先に通常の `<summary>` を記述する．

        /// <inheritdoc/>
        public override bool Connect() { ... }

    ■ 他メンバーへの参照
    ・説明文中で他のクラスやメンバーを参照する場合は `<see cref="..."/>` を使用する．

        /// <summary>
        /// <see cref="Config"/> から設定値を読み込む
        /// </summary>
        public void Load() { ... }

        /// <summary>
        /// 接続に失敗した場合は <see cref="ErrorMsg"/> を参照すること
        /// </summary>
        public bool Connect() { ... }

2-2. フィールド・定数コメント (Field / Constant Comment)
    ・公開される定数・フィールドにはインラインコメント（`//`）を直前行に記述する．
    ・書式:

        // [その定数・フィールドが何を表すかを端的に説明]
        public static string ConstantName = value;

    ・例:

        // アプリケーション名
        public static string APP_NAME = "TIAS Shot";

        // 校正中フレームのカウンタ（0 より大きければ校正中）
        protected int _calibrating = 0;

2-3. ブロックコメント (Block Comment)
    ・メソッド内で処理のまとまりが変わる箇所に記述する．
    ・`//` + 半角スペースを使用する．
    ・書式:

        // [このブロックの処理を端的に説明]
        ...処理...

    ・例:

        // ARマーカー検出
        CvAruco.DetectMarkers(img, ARDict, out var corners, out var ids, ...);

        // チャートの固定判定
        var dist = (float)position.DistanceTo(_lastPosition);

2-4. タスクコメント (Task Comment)
    ・後で対応が必要な箇所に記述し，担当者と内容を明記する．
    ・書式:

        // [タグ]([担当者名]): [内容]

    ■ タグ定義:
    - TODO  : 将来的に実装・対応が必要な箇所
    - FIXME : 既知のバグや不具合があり修正が必要な箇所
    - HACK  : 意図的な暫定対応であり，本来あるべき実装ではない箇所

    ・例:

        // TODO(yamada): タイムアウト処理を実装する
        // FIXME(tanaka): 負の距離が入力された場合にクラッシュする
        // HACK(suzuki): API 仕様確定まで固定値で代替している

    ・注意:
        - 「いつか直す」ではなく，必ずタスク管理ツールとセットで運用する
        - FIXME はリリース前に必ず解消する
        - HACK は技術的負債として定期的に見直す


3. 記述しない場合の判断基準 (When to Omit)
------------------------------------------------------------------------
・ファイル内部でのみ使用し，外部に公開されない private メンバーは省略してもよい
・コード自体が自明な場合（メンバー名で意図が十分伝わる場合）は省略してもよい
・自動生成コード（`*.Designer.cs` 等）は対象外とする


4. NG例 (Anti-patterns)
------------------------------------------------------------------------
・句点を付ける
    - NG: /// <summary>画像を保存する．</summary>
    - OK: /// <summary>画像を保存する</summary>

・「、」「。」を使う
    - NG: // 撮影開始時の基準座標をセットする。
    - OK: // 撮影開始時の基準座標をセットする

・コードをコメントアウトして残す
    - NG: //_lucam.StartStopPreview();
    - OK: 不要なコードは削除する（Git 履歴から復元できる）

・XML doc comment を通常コメントで書く
    - NG: // Connect: デバイスに接続する
    - OK: /// <summary>デバイスに接続する</summary>