diff --git a/CLAUDE.md b/CLAUDE.md index 605ed70..f432105 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,48 +1,51 @@ -# CLAUDE.md +# プロジェクト名 -このプロジェクトでは `docs/01_GUIDE/` 以下に定義されたルールを必ず遵守すること。 -各ファイルの詳細はリンク先を参照する。 + ---- +## 開発進捗 -## ドキュメント作成 +現在の進捗: GUIDE_01 に従いプロジェクト立ち上げ中 +※ ステップ完了時にここを更新すること． -[GUIDE_01_ドキュメント作成ガイド.txt](docs/01_GUIDE/GUIDE_01_ドキュメント作成ガイド.txt) +## 必須ルール（コード実装時） -テキストドキュメントの書式全般を定義する。句読点は「，」「．」を使用し「、」「。」は使わない。 -見出し階層（大見出し・中見出し・■・・・・-）や空行ルールに従うこと。 + ---- +### Git 運用（GUIDE_04 準拠） -## ファイル命名 +- ブランチ名: `feature/`/`fix/`/`docs/`/`chore/` + 英単語 2〜4 語（kebab-case） +- コミットメッセージ: `[add]`/`[update]`/`[fix]`/`[remove]`/`[clean]` + 日本語 +- コミット・push 後は `gh pr create` で PR を作成する -[GUIDE_02_ドキュメント命名規則.txt](docs/01_GUIDE/GUIDE_02_ドキュメント命名規則.txt) +### 手動確認が必要な作業（自分で完了させないこと） -ドキュメントファイルは `[カテゴリ]_[連番]_[名称].txt` の形式で命名する。 -カテゴリ（GUIDE / PLAN / ENV / SPEC / TECH / TEST / ADR）の定義もここに記載されている。 +以下は実装完了後にユーザーへ報告し，確認・実施を依頼すること． ---- +- 外部サービスの設定（コンソール操作，セキュリティルール変更等） +- 実機・ブラウザでの動作確認 +- ストアへのアップロード・リリース作業 -## Git 運用 +## ドキュメント -[GUIDE_03_Git運用ルール.txt](docs/01_GUIDE/GUIDE_03_Git運用ルール.txt) +設計・規約に関する情報は docs/ にある． +コードを書く前に関連するファイルを読むこと． -ブランチ命名（`feature/`・`fix/`・`refactor/` 等），コミットメッセージのタグ（`[add]`・`[update]`・`[fix]`・`[remove]`・`[clean]`），PR フロー（必ず PR 経由でマージ，直プッシュ禁止）を定義する。 +### 01_GUIDE（規約・ルール） ---- +- プロジェクト立ち上げフロー: docs/01_GUIDE/GUIDE_01_プロジェクト立ち上げフロー.md +- ドキュメント作成規約: docs/01_GUIDE/GUIDE_02_ドキュメント作成ガイド.md +- ファイル命名規則: docs/01_GUIDE/GUIDE_03_ファイル命名規則.md +- Git 運用ルール: docs/01_GUIDE/GUIDE_04_Git運用ルール.md +- ※ コーディング規約，テスト方針等はプロジェクト立ち上げ時に作成する（GUIDE_01 参照） -## コーディング規則 +### 02_ENV（環境） -[GUIDE_04_コーディング規則.txt](docs/01_GUIDE/GUIDE_04_コーディング規則.txt) + -C# コードの書き方を定義する。Microsoft コーディング規則準拠，PascalCase / camelCase / `_camelCase` の使い分け， -波括弧スタイル（同一行），`var` の使用方針，マジックナンバー禁止など。 +### 03_PLAN（計画） ---- + -## コードコメント規則 +### 04_SPEC（仕様・設計） -[GUIDE_05_コードコメント規則.txt](docs/01_GUIDE/GUIDE_05_コードコメント規則.txt) - -コメント・XML ドキュメントコメントの書き方を定義する。クラス・public / protected メンバーには `/// ` 必須。 -コメントは日本語，句読点は「，」を使用，文末の「．」は付けない。 + diff --git "a/docs/01_GUIDE/GUIDE_01_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.txt" "b/docs/01_GUIDE/GUIDE_01_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.txt" deleted file mode 100644 index 8dafd98..0000000 --- "a/docs/01_GUIDE/GUIDE_01_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.txt" +++ /dev/null @@ -1,146 +0,0 @@ -======================================================================== -ドキュメント作成ガイドライン (Style Guide) -======================================================================== - -1. 基本フォーマット (Basic Format) ------------------------------------------------------------------------- -・文字コード: UTF-8 -・改行コード: LF (推奨) または CRLF -・インデント: 半角スペース4つ (4 spaces) - - タブ文字は使用せず，スペースに展開して揃える． -・ファイル命名: `GUIDE_02_ドキュメント命名規則.txt` を参照する． - -■ ファイルヘッダー (File Header) -・ファイルの先頭には必ずタイトルブロックを記述する． -・書式: 上下を「=」（イコール）の列（72文字程度）で挟む． -・例: - ======================================================================== - ドキュメントタイトル (English Title) - ======================================================================== - - -2. 句読点・約物 (Punctuation) ------------------------------------------------------------------------- -・句読点: 「，」（全角カンマ）と「．」（全角ピリオド）を使用する． - - 「、」「。」は使用しない． -・コロン: 半角コロン＋半角スペース「: 」を使用する． - - NG: 全角コロン「：」，スペースなし「:」 -・括弧: 原則として半角括弧 `( )` を使用するが，強調や補足には全角 `（ ）` や `「 」` も許容する． -・注釈: 文末や段落末の補足には「※」（全角米印）＋半角スペースを使用する． - - 例: ※ shared は client/server 両方から import して使用する． - - -3. 階層構造と見出し (Headings & Hierarchy) ------------------------------------------------------------------------- - -3-1. レベル1：大見出し (Section) - ・書式: 数字 + ドット + 半角スペース + タイトル + (英語タイトル) - ・装飾: 下行にハイフン「-」による区切り線を挿入する． - ・例: - 1. 基本設計 (Basic Design) - ------------------------------------------------------------------------ - -3-2. レベル2：中見出し (Subsection) - ・書式: 数字-数字 + ドット + 半角スペース + タイトル - ・例: - 1-1. 製品概要 - -3-3. レベル3：小見出し (Group Heading) - ・書式: 「■」＋ 半角スペース ＋ タイトル - ・使い分け: - - セクション内で独立したトピック（カテゴリ）を列挙する場合は「■」を使用する． - - 手順やフロー、順序のある項目を示す場合は「1. 」「2. 」を使用する． - - A. 並列・カテゴリ列挙（順序不問） - - 記号: 「■ 」（全角四角＋半角スペース） - - 例: ■ フィールド仕様 - - B. 手順・優先順位・ランキング（順序重要） - - 記号: 「1. 」「2. 」（半角数字＋ドット＋半角スペース） - - 例: 1. ユーザ体験の理想 - -3-4. レベル4：リスト項目 (List Item) - ・記号: 「・」（全角中黒） - ・書式: 「・項目名: 内容」または「・項目名」のみ． - ・使いどころ: セクション内の主要な列挙（親項目）に使用する． - ・例: - ・タイトル: Paint War - -3-5. レベル5：詳細項目 (Detail Item) - ・記号: 「- 」（半角ハイフン＋半角スペース） - ・インデント: 親項目のテキスト開始位置に合わせる（基本はスペース8つ）． - ・使いどころ: 親が「・」のとき，その補足・条件・内訳を子項目として記述する． - ・ルール: 親が「・」なら子は必ず「- 」を使う． - ・例: - ・接続設定 - - host: localhost - - port: 3000 - -3-6. 特殊なナンバリング (Zero Indexing) - ・目的定義: セクションの冒頭で目的や定義を述べる場合，「X-0. 目的」というナンバリング（ゼロ始まり）を使用してもよい． - - 例: 1-0. 目的 - -3-7. 階層の順守 - ・上位レベルから下位レベルへ順に記述し，階層を飛ばさないこと． - - NG例: レベル1（1. XX）の直下にレベル3（■ XX）を記述する． - - 対策: 必要に応じてレベル2（1-1. 概要 等）を設ける． - - -4. 余白・改行ルール (Spacing) ------------------------------------------------------------------------- -・大見出しの上: 2行空ける． -・中見出し（X-X）の上: 1行空ける． -・小見出し（■や数字）の上: 1行空ける． -・セクション内のリスト: 原則として行間を詰め，まとまりごとに適宜空行を入れる． -・ミニサンプル: - 1. 基本設計 (Basic Design) - ------------------------------------------------------------------------ - - - 1-1. 製品概要 - - ■ 主要要件 - ・要件A: 説明 - ・要件B: 説明 - - ■ 補足 - ・注意点: 説明 - -・NG例（空行不足）: - 1. 基本設計 (Basic Design) - ------------------------------------------------------------------------ - 1-1. 製品概要 - ■ 主要要件 - ・要件A: 説明 - - -5. 技術記述・コード表記 (Technical & Code) ------------------------------------------------------------------------- -・1行の最大文字数: 半角80文字（全角40文字）を目安とする．超える場合は適切な位置で折り返す． - -・インラインコード: バッククォート1つで囲む． - - 例: `MAX_DIST`，`useJoystick`，`.env` - -・コマンドライン: 先頭に `$ ` を付与して区別する． - - 例: - - $ git checkout -b feature/260314_yamada_new_function - $ npm install - -・コードブロック: 親の箇条書きレベルに合わせてインデントし，前後に1行空ける． - - 例: - - // 入力座標からベクトルを計算し，半径でクランプして正規化出力する - const handleMove = (e: PointerEvent) => { - const dx = e.clientX - origin.x; - const dy = e.clientY - origin.y; - }; - -・ディレクトリ構造: ツリー記号（`├──`，`│`，`└──`）を使用し，ルートディレクトリからの階層を示す． - - 例: - - src/ - ├── components/ - │ └── Joystick.tsx - └── hooks/ - └── useJoystick.ts \ No newline at end of file diff --git "a/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" "b/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" new file mode 100644 index 0000000..f9aa80e --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" @@ -0,0 +1,113 @@ +# プロジェクト立ち上げフロー (Project Setup Flow) + +新規プロジェクトを AI と協働で立ち上げる際の手順を定義する． +各フェーズを順番に進め，成果物を確定させてから次のフェーズに移ること． + +## フェーズ一覧 (Phase Overview) + +| フェーズ | やること | 成果物 | +| -------- | ---------------------------------------------- | ---------------------------------------------------------- | +| 方針決定 | プロジェクトの目的・スコープを決める | `PLAN_01_要件定義書.md` | +| 技術選定 | 言語・フレームワーク・インフラを決める | `ENV_01_技術スタック.md` | +| 環境構築 | 開発環境のセットアップ手順を整備する | `ENV_02_環境構築手順.md`，`ENV_03_管理者用環境構築手順.md` | +| 仕様設計 | アーキテクチャ・データモデル・画面設計を決める | `SPEC_01_*.md` | +| 規約整備 | 技術スタックに応じたコーディング規約を作る | `GUIDE_*_*.md` | +| 開発計画 | ステップを分割し，開発順序を決める | `PLAN_02_開発ステップ.md` | +| 実装開始 | 開発計画に沿って実装を進める | ソースコード | + +## 方針決定 (Direction) + +プロジェクトの全体像を明確にする． + +- **人間が決めること**: プロジェクトの目的，対象ユーザー，スコープ（やること・やらないこと） +- **AI に依頼できること**: 要件の整理・構造化，類似プロジェクトの調査，要件定義書のドラフト作成 +- **成果物**: `PLAN_01_要件定義書.md` + +## 技術選定 (Tech Stack) + +要件に基づいて技術スタックを決定する． + +- **人間が決めること**: 最終的な技術選定の判断，チームのスキルセットとの適合性 +- **AI に依頼できること**: 要件に適した技術の候補提案，各候補のメリット・デメリット比較 +- **成果物**: `ENV_01_技術スタック.md` + +## 環境構築 (Environment Setup) + +開発環境を構築し，手順をドキュメント化する．初回のみの管理者作業と，メンバーが繰り返し行う構築手順を分けて整備する． + +- **前提条件**: 以下のツールは全プロジェクト共通で導入する． + - `git` — バージョン管理（[GUIDE_04](GUIDE_04_Git運用ルール.md) で運用ルールを定義） + - `gh` — GitHub CLI（PR 作成・マージ等に使用） +- **基本方針**: 環境の再現性を重視し，手順書だけに頼らず構築を自動化・コード化できる方法を優先する（例: Docker，Dev Containers，Windows Sandbox，IaC ツール等）． +- **人間が決めること**: 開発マシンの選定，クラウドサービスのアカウント作成，環境構築方法の選択 +- **AI に依頼できること**: 環境構築手順書の作成，設定ファイルの生成，`.gitignore` の作成，Dockerfile や devcontainer.json 等の構築用ファイルの作成 +- **成果物**: + - `ENV_02_環境構築手順.md` — メンバーの参加時や環境の再構築時に使う手順 + - `ENV_03_管理者用環境構築手順.md` — プロジェクト作成時に一度だけ行う初期設定（リポジトリ作成，外部サービスの設定等） + +## 仕様設計 (Specification) + +アプリケーションの設計を行う． + +- **人間が決めること**: ユーザー体験の方針，ビジネスロジックの最終判断 +- **AI に依頼できること**: アーキテクチャ設計のドラフト，データモデル定義，画面遷移図の整理 +- **成果物**: `SPEC_01_*.md`（プロジェクトの規模に応じて複数ファイルに分割） + +## 規約整備 (Coding Standards) + +技術スタックに応じたコーディング規約やプロジェクト固有のガイドを作成する． +汎用ガイド（GUIDE_01〜04）は本テンプレートに含まれている．ここではプロジェクト固有の規約を追加する． + +- **基本方針**: 言語・フレームワークの公式ガイドラインや広く採用されている標準規約に則る（例: Effective Dart，PEP 8，Google Style Guide 等）．プロジェクト固有のルールは標準と異なる部分のみ定義する． +- **人間が決めること**: 標準規約でカバーされない判断（アーキテクチャパターンの選択等） +- **AI に依頼できること**: 標準規約を踏まえた規約のドラフト作成，参照元ガイドラインの調査 +- **作成すべきガイド**: + - コーディング規約 — 命名規則，フォーマット，import 順序，型の使い方，コメントの書き方，コード内ドキュメントの規則 + - ディレクトリ構造規則 — プロジェクトのディレクトリ構成とファイル配置ルール + - テスト方針 — テストの種類，粒度，実行タイミング，カバレッジ基準 + - エラーハンドリング方針 — エラーの分類，処理方法，ログ出力の方針 + - リファクタリング方針 — リファクタリングの判断基準，実施タイミング + - 機能実装完了フロー — コミット前のチェックリスト（フォーマット，静的解析，テスト，レビュー等） + +## 開発計画 (Development Plan) + +実装の順序とステップを決定する． + +- **人間が決めること**: 優先度，リリース計画，マイルストーン +- **AI に依頼できること**: 仕様を元にしたステップ分割の提案，依存関係の整理 +- **成果物**: `PLAN_02_開発ステップ.md` + +## 実装開始 (Implementation) + +開発計画に沿って AI と協働で実装を進める． + +- 各ステップの完了時に [GUIDE_02_ドキュメント作成ガイド](GUIDE_02_ドキュメント作成ガイド.md) と [GUIDE_04_Git運用ルール](GUIDE_04_Git運用ルール.md) に従ってコミット・PR を作成する． +- 仕様変更が発生した場合は，先にドキュメントを更新してから実装に反映する． + +### ドキュメントの書き方 + +- コード内ドキュメント（JSDoc・コメント）と docs/ ドキュメントの書き方は [GUIDE_05_コーディング規約](GUIDE_05_コーディング規約.md) の「ドキュメント」セクションを参照 +- 仕様・設計の変更がある場合は `docs/` を先に更新してから実装に反映する + +## CLAUDE.md の管理 (CLAUDE.md Management) + +`CLAUDE.md` は AI が会話開始時に最初に読むファイルであり，プロジェクトの引継ぎ情報を一元管理する． +AI は毎回新しい会話で始まるため，このファイルが唯一の継続的な文脈となる． + +### 記載すべき内容 + +- **プロジェクト概要**: プロジェクト名，目的，技術スタックの要約 +- **開発進捗**: 現在のステップ，次にやること +- **必須ルール**: AI が実装時に必ず守るべきルール（コーディング規約，コミット前チェック等の要点） +- **ドキュメント一覧**: docs/ 内のファイルへの参照パス + +### 更新タイミング + +- ステップの完了時に開発進捗を更新する +- ドキュメントの追加・削除・リネーム時に参照パスを更新する +- 必須ルールに変更があった場合に反映する + +### 運用上の注意 + +- CLAUDE.md は AI が毎回読み込むため，簡潔に保つ．詳細は docs/ のドキュメントに委ね，CLAUDE.md には要点と参照先のみ記載する． +- プロジェクト固有のルールが増えたら，docs/ に独立ファイルとして切り出し，CLAUDE.md からはリンクで参照する． diff --git "a/docs/01_GUIDE/GUIDE_02_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.md" "b/docs/01_GUIDE/GUIDE_02_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.md" new file mode 100644 index 0000000..ed91906 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_02_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.md" @@ -0,0 +1,114 @@ +# ドキュメント作成ガイドライン (Documentation Style Guide) + +本ガイドはプロジェクト内のマークダウンドキュメントの書式を統一するためのルールを定める． +基本方針として [Google Markdown Style Guide](https://google.github.io/styleguide/docguide/style.html) および [markdownlint](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) のルールに準拠し，本ガイドで上書きする項目のみ以下に記載する． + +## 基本フォーマット (Basic Format) + +- 文字コード: UTF-8 +- 改行コード: LF（推奨）または CRLF +- ファイル拡張子: `.md` +- ファイル末尾: 空行を 1 行入れて終了する（MD047） + +## 句読点・約物 (Punctuation) + +- 句読点: 「，」（全角カンマ）と「．」（全角ピリオド）を使用する． + - 「、」「。」は使用しない． +- コロン: 半角コロン＋半角スペース「: 」を使用する． + - NG: 全角コロン「：」，スペースなし「:」 +- 括弧: 原則として半角 `( )` を使用する．強調や補足には全角 `（ ）` や `「 」` も許容する． +- 注釈: 補足には「※」（全角米印）＋半角スペースを使用する． + - 例: ※ shared は client/server 両方から import して使用する． + +## 見出し (Headings) + +ATX スタイル（`#`）を使用する．Setext スタイル（`===` / `---` の下線）は使用しない． + +- `#` の後に半角スペースを 1 つ入れる（MD018） +- 見出しの前後に空行を 1 行入れる（MD022） +- 見出しレベルは飛ばさない（MD001） + - NG: `#` の直下に `###` +- ドキュメント内の `#`（H1）は 1 つだけにする（MD025） +- 見出しには番号を付けない．マークダウンの見出し構造で階層を表現する． +- 見出しの書式: `タイトル (English Title)` + - 例: `## 基本設計 (Basic Design)` + +### 見出しレベルの対応表 + +| レベル | 記法 | 用途 | +| --- | --- | --- | +| H1 | `#` | ドキュメントタイトル（ファイルに 1 つ） | +| H2 | `##` | 大見出し（セクション） | +| H3 | `###` | 中見出し（サブセクション） | +| H4 | `####` | 小見出し（トピック） | + +## リスト (Lists) + +- 箇条書きには `- `（半角ハイフン＋半角スペース）を使用する（MD004） + - `*` `+` `・` は使用しない． +- ネストは 2 スペースでインデントする（MD007） +- 順序付きリストは `1.` の連番で記述する． +- リストの前後に空行を 1 行入れる（MD032） + +## 強調 (Emphasis) + +- 太字: `**テキスト**` を使用する．`__テキスト__` は使用しない（MD050） +- 斜体: `*テキスト*` を使用する．`_テキスト_` は使用しない（MD049） +- 太字斜体: `***テキスト***` を使用する． + +## コードブロック・インラインコード (Code) + +- コードブロックにはフェンス（` ``` `）を使用し，言語名を明記する（MD040） + + ````markdown + ```dart + final name = 'DxNavi'; + ``` + ```` + +- インラインコードにはバッククォート `` ` `` を使用する． + - 例: `build_runner` コマンドを実行する． +- コマンド例にはシェル言語を指定する． + + ````markdown + ```bash + dart run build_runner build --delete-conflicting-outputs + ``` + ```` + +## リンク・画像 (Links & Images) + +- リンク: `[テキスト](URL)` 形式を使用する． +- 画像: `![代替テキスト](パス)` 形式を使用し，代替テキストを必ず記述する（MD045） +- プロジェクト内リンクは相対パスを使用する． + +## テーブル (Tables) + +- ヘッダー行とセパレータ行を必ず含める． +- セル内は簡潔に記述し，長い場合はリンクや脚注で補足する． + +```markdown +| 項目 | 説明 | +| --- | --- | +| 名前 | 値 | +``` + +## 空行・余白 (Spacing) + +- 連続する空行は最大 1 行までとする（MD012） +- 見出し・リスト・コードブロックの前後に空行を 1 行入れる（MD022, MD031, MD032） +- 行末の不要な空白は削除する（MD009） + +## その他 (Miscellaneous) + +- HTML タグは原則使用しない．マークダウン記法で表現できない場合のみ許容する． +- 1 行の長さに厳密な上限は設けないが，可読性のために適度に改行する． +- ディレクトリ構造の表現にはコードブロック内でツリー記号（`├──`，`│`，`└──`）を使用する． + +```text +project/ +├── lib/ +│ ├── core/ +│ └── features/ +└── test/ +``` diff --git "a/docs/01_GUIDE/GUIDE_02_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\345\221\275\345\220\215\350\246\217\345\211\207.txt" "b/docs/01_GUIDE/GUIDE_02_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\345\221\275\345\220\215\350\246\217\345\211\207.txt" deleted file mode 100644 index b98ff35..0000000 --- "a/docs/01_GUIDE/GUIDE_02_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\345\221\275\345\220\215\350\246\217\345\211\207.txt" +++ /dev/null @@ -1,68 +0,0 @@ -======================================================================== -ドキュメント管理・ファイル命名規則 (File Naming Conventions) -======================================================================== - -1. 命名の基本方針 (Basic Policy) ------------------------------------------------------------------------- -プロジェクトの規模拡大に伴うファイルの散乱を防ぎ，開発メンバーおよびAI（Gemini/Copilot）がファイルの内容・文脈を即座に特定できるようにするため，以下の規則を適用する． -※ 書式・記述スタイルの基準は `GUIDE_01_ドキュメント作成ガイド.txt` を参照する． - -1-1. 基本フォーマット -`[カテゴリ]_[連番]_[ファイル名].txt` - -・区切り文字: アンダースコア `_` を使用する． -・連番: 01から始まる2桁の数字とする． -・拡張子: プレーンテキスト `.txt` とする． - -1-2. ファイル名部分の規則 -・言語: 日本語を推奨する（例: `通信プロトコル仕様`，`環境構築手順`）． -・使用可能文字: 日本語，英数字，アンダースコア `_` のみとする． - - NG: スペース，ハイフン，記号（`/`，`.`，`(` 等） -・文字数: 全角20文字（半角40文字）以内を目安とする． -・例: - - OK: `TECH_01_通信プロトコル仕様.txt` - - OK: `ENV_01_環境構築手順.txt` - - NG: `TECH_01_通信 プロトコル仕様（v2）.txt` - - -2. カテゴリ定義 (Category Definitions) ------------------------------------------------------------------------- -ファイル名の先頭に付与するプレフィックス（接頭辞）定義． - -■ GUIDE_ (Guide) -・内容: チーム全体のルール，規約，運用フローなど，「メタ情報」に関する定義． -・対象例: スタイルガイド，命名規則，Git運用ルール． - -■ PLAN_ (Planning) -・内容: プロジェクトの進行計画，スケジュール，要件定義など，「管理・進行」に関する定義． -・対象例: WBS，ロードマップ，要件定義書，タスク一覧． - -■ ENV_ (Environment) -・内容: 開発環境，ディレクトリ構造，ライブラリ選定など，プロジェクトの「土台」に関する定義． -・対象例: 環境構築手順，技術スタック一覧，パッケージ構成図． - -■ SPEC_ (Specification) -・内容: 機能要件，UI/UXなど，ユーザーから見える「仕様」に関する定義． -・対象例: 機能仕様書，画面遷移図，操作手順，ユーザー向けパラメータ定義． - -■ TECH_ (Technical) -・内容: 実装詳細，アルゴリズム，データ構造など，エンジニア向けの「技術設計」に関する定義． -・対象例: 通信プロトコル仕様，同期ロジック，データベース設計，クラス設計． - -■ TEST_ (Test) -・内容: テスト計画，テストケース，品質保証手順など，「検証・品質」に関する定義． -・対象例: 単体テスト仕様書，シナリオテスト計画，テストケース一覧，品質基準． - -■ ADR_ (Architecture Decision Record) -・内容: 設計上の意思決定とその根拠，採用・却下の経緯など，「なぜその設計にしたか」の記録．重要な判断をした時点で必ず作成する． -・対象例: 通信方式の選定理由，ライブラリ採用経緯，大きな設計変更の背景． - - -3. 運用ルール (Operational Rules) ------------------------------------------------------------------------- -・1ファイル1テーマ: - ファイルサイズが肥大化しすぎないよう，トピック（例: 通信仕様，判定ロジック）ごとにファイルを分割することを推奨する． - これにより，AIへのコンテキスト入力精度が向上する． - -・スタイルの継承: - 新規作成するファイルも，必ず `GUIDE_01_ドキュメント作成ガイド.txt` に記載された書式（見出し，句読点「，．」等）に従うこと． \ No newline at end of file diff --git "a/docs/01_GUIDE/GUIDE_03_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.txt" "b/docs/01_GUIDE/GUIDE_03_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.txt" deleted file mode 100644 index 4fb7537..0000000 --- "a/docs/01_GUIDE/GUIDE_03_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.txt" +++ /dev/null @@ -1,145 +0,0 @@ -======================================================================== -Git運用ルール (Git Operation Rules) -======================================================================== - -1. 基本方針 (Basic Policy) ------------------------------------------------------------------------- -チーム開発におけるコードの整合性を保ち，手戻りを防ぐために以下の運用フローを徹底する． - -・メインブランチ (main): - - 本番環境または常に動作可能な状態を維持するブランチ． - - 直接のコミット（直プッシュ）は禁止する．必ずプルリクエスト（PR）経由でマージする． -・作業ブランチ (Feature Branch): - - 機能追加やバグ修正ごとに `main` から派生させて作成する． - - 作業完了後，`main` へマージし，原則として削除する． -・`.gitignore`: - - リポジトリ作成時に必ず整備する． - - ビルド成果物，依存パッケージ（`node_modules/` 等），環境変数ファイル（`.env` 等）は必ず除外する． - - `git add .` を安全に使うための前提条件であるため，メンバー追加時にも確認する． - - -2. ブランチ命名規則 (Branch Naming) ------------------------------------------------------------------------- -2-1. プレフィックス (Prefix) -作業の種類を一目で判別するために，以下のプレフィックスを使用する． - -■ カテゴリ一覧 - ・feature/: 新機能の実装，仕様変更 - ・fix/: バグ修正 - ・refactor/: コードの整理（挙動は変えない） - ・docs/: ドキュメントの追記・修正 - ・chore/: ビルド設定やツール導入など，雑多な作業 - -2-2. 書式 (Format) - ・書式: `[プレフィックス][概要]` - ・区切り: スラッシュ `/` を使用する．概要内の単語区切りはハイフン `-` を使用する． - ・概要: 作業内容を端的に表す英単語2〜4語程度（小文字）とする． - ・例: - - feature/player-jump - - fix/collision-bug - - docs/guide-update - - -3. 開発フロー (Development Workflow) ------------------------------------------------------------------------- -作業を開始してからマージされるまでの手順． - -1. ローカルの最新化 - ・作業開始前は必ず `main` ブランチに切り替え，リモートの最新状態を取り込む． - ・コマンド: - $ git checkout main - $ git pull origin main - -2. 作業ブランチの作成 - ・最新の `main` から新しいブランチを作成して移動する． - ・コマンド: - $ git checkout -b feature/new-function - -3. 実装とコミット - ・作業単位（意味のあるまとまり）ごとにコミットする． - ・巨大なコミットは避け，レビューしやすい粒度を心がける． - ・VS CodeでCopilotを使用している場合，AIによるコミットメッセージの生成機能（キラキラアイコン等）を利用してもよい． - ただし，生成されたメッセージは必ず「4. コミットメッセージ」の書式ルール（タグや日本語化）に合わせて修正すること． - ・コマンド: - $ git add . - $ git commit -m "[add] 新機能を実装" - -4. リモートへのプッシュ - ・作業ブランチをリモートリポジトリへ送信する． - ・コマンド: - $ git push origin feature/new-function - -5. プルリクエスト (PR) の作成 - ・GitHubのリポジトリ画面上部に表示される「Compare & pull request」ボタンをクリックする． - ・Baseを `main`、Compareを自分の「作業ブランチ」に設定する． - ・「Reviewers」メニューからチームメンバーを選択し、レビューを依頼する． - ・「Create pull request」ボタンを押してPRをオープンする． - -6. レビューと修正の対応 - ・レビュワーのコメントを確認し、修正が必要な場合はローカルで修正・コミット・プッシュを繰り返す． - ・GitHub上で全ての指摘に対し「Resolve conversation」を行い、やり取りを完了させる． - ・レビュワーから「Approve（承認）」のスタンプまたはメッセージをもらう． - -7. マージの実行（マージボタンの操作） - ・PR画面下部の「Merge pull request」ボタンをクリックする． - ・マージ方式は「Create a merge commit」を選択する（作業ブランチの全コミット履歴が `main` に残る）． - - 「Squash and merge」「Rebase and merge」は使用しない． - ・確認用の「Confirm merge」ボタンを押し，`main` への統合を完了させる． - ・マージ直後に表示される「Delete branch」ボタンを押し，リモート上の作業ブランチを削除する． - -8. ローカル環境のクリーンアップ - ・マージ完了後はローカル環境も最新状態に戻し、古いブランチを削除する． - $ git checkout main - $ git pull origin main - $ git branch -d [作業ブランチ名] - - -4. コミットメッセージ (Commit Messages) ------------------------------------------------------------------------- -4-1. 書式 - ・書式: `[タグ] 内容` - ・言語: 日本語 (Japanese) - ・句読点: 末尾に句点は不要． - -4-2. タグ一覧 - ・[add]: ファイルや機能の追加 - ・[update]: 機能やデータの更新・修正 - ・[fix]: バグ修正 - ・[remove]: 削除 - ・[clean]: 整理，リファクタリング - - -5. トラブルシューティング (Troubleshooting) ------------------------------------------------------------------------- -■ コンフリクト (Conflict) が発生した場合 -他メンバーの変更と競合した場合の対処手順． - -1. main の取り込み - ・作業ブランチに `main` の最新内容をリベースして競合箇所を洗い出す． - ・`merge` ではなく `rebase` を使うことで，履歴が線形に保たれレビューしやすくなる． - ・コマンド: - $ git checkout main - $ git pull origin main - $ git checkout feature/new-function - $ git rebase main - -2. 競合の解消 - ・エディタ上で `<<<<<<<`, `=======`, `>>>>>>>` で囲まれた箇所を手動で修正する． - ・修正後，以下のコマンドでリベースを続行する． - $ git add [修正したファイル] - $ git rebase --continue - ・全ての競合が解消されたらプッシュする．リベース後は履歴が書き換わるため `-f` オプションが必要になる． - $ git push -f origin feature/new-function - -■ 間違えて main にコミットしてしまった場合 - -1. まだプッシュしていない場合 - ・コミットを取り消し，変更内容を保持したまま新しいブランチへ移動する． - ・コマンド: - $ git reset --soft HEAD^ - $ git checkout -b feature/new-function - $ git commit -m "[add] ..." - -2. すでにプッシュしてしまった場合 - ・`main` への force push はチーム全員の履歴を壊す危険があるため，自分では対処しない． - ・直ちにチームメンバーに報告し，全員で対応方針を決める． \ No newline at end of file diff --git "a/docs/01_GUIDE/GUIDE_03_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.md" "b/docs/01_GUIDE/GUIDE_03_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.md" new file mode 100644 index 0000000..f9d43d2 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_03_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.md" @@ -0,0 +1,31 @@ +# ドキュメント管理・ファイル命名規則 (File Naming Conventions) + +## 命名の基本方針 (Basic Policy) + +プロジェクトの規模拡大に伴うファイルの散乱を防ぎ，開発メンバーおよび AI がファイルの内容・文脈を即座に特定できるようにするため，以下の規則を適用する． + +### 基本フォーマット + +`[カテゴリ]_[連番]_[ファイル名].md` + +- 区切り文字: アンダースコア `_` を使用する． +- 連番: 01 から始まる 2 桁の数字とする． +- 拡張子: マークダウン `.md` とする． + +## カテゴリ定義 (Category Definitions) + +ファイル名の先頭に付与するプレフィックス（接頭辞）定義． + +| カテゴリ | ディレクトリ | 内容 | 対象例 | +| --- | --- | --- | --- | +| `GUIDE_` | `01_GUIDE/` | ルール，規約，運用フロー | スタイルガイド，命名規則，Git 運用ルール | +| `ENV_` | `02_ENV/` | 開発環境，プロジェクトの土台 | 環境構築手順，技術スタック一覧，パッケージ構成図 | +| `PLAN_` | `03_PLAN/` | 進行計画，スケジュール，要件定義 | WBS，ロードマップ，要件定義書，タスク一覧 | +| `SPEC_` | `04_SPEC/` | ユーザーから見える仕様 | 企画書，画面遷移図，パラメータ設定 | +| `TECH_` | `05_TECH/` | エンジニア向けの技術設計 | 通信プロトコル仕様，データベース設計，クラス設計 | +| `TEST_` | `06_TEST/` | テスト計画，品質保証 | 単体テスト仕様書，シナリオテスト計画，品質基準 | + +## 運用ルール (Operational Rules) + +- 1 ファイル 1 テーマ: ファイルサイズが肥大化しすぎないよう，トピックごとにファイルを分割することを推奨する．これにより，AI へのコンテキスト入力精度が向上する． +- スタイルの継承: 新規作成するファイルも，必ず [GUIDE_02_ドキュメント作成ガイド](GUIDE_02_ドキュメント作成ガイド.md) に記載された書式に従うこと． diff --git "a/docs/01_GUIDE/GUIDE_04_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" "b/docs/01_GUIDE/GUIDE_04_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" new file mode 100644 index 0000000..3b79351 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_04_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" @@ -0,0 +1,181 @@ +# Git 運用ルール (Git Operation Rules) + +## 基本方針 (Basic Policy) + +チーム開発におけるコードの整合性を保ち，手戻りを防ぐために以下の運用フローを徹底する． + +- **メインブランチ (main)**: + - 本番環境または常に動作可能な状態を維持するブランチ． + - 直接のコミット（直プッシュ）は禁止する．必ずプルリクエスト（PR）経由でマージする． +- **作業ブランチ (Feature Branch)**: + - 機能追加やバグ修正ごとに `main` から派生させて作成する． + - 作業完了後，`main` へマージし，原則として削除する． +- **`.gitignore`**: + - リポジトリ作成時に必ず整備する． + - ビルド成果物，依存パッケージ（`node_modules/` 等），環境変数ファイル（`.env` 等）は必ず除外する． + - `git add .` を安全に使うための前提条件であるため，メンバー追加時にも確認する． + +## ブランチ命名規則 (Branch Naming) + +### プレフィックス (Prefix) + +作業の種類を一目で判別するために，以下のプレフィックスを使用する． + +| プレフィックス | 用途 | +| --- | --- | +| `feature/` | 新機能の実装，仕様変更 | +| `fix/` | バグ修正 | +| `refactor/` | コードの整理（挙動は変えない） | +| `docs/` | ドキュメントの追記・修正 | +| `chore/` | ビルド設定やツール導入など，雑多な作業 | + +### 書式 (Format) + +- 書式: `[プレフィックス][概要]` +- 区切り: スラッシュ `/` を使用する．概要内の単語区切りはハイフン `-` を使用する． +- 概要: 作業内容を端的に表す英単語 2〜4 語程度（小文字）とする． +- 例: + - `feature/player-jump` + - `fix/collision-bug` + - `docs/guide-update` + +## 開発フロー (Development Workflow) + +作業を開始してからマージされるまでの手順． + +### ローカルの最新化 + +作業開始前は必ず `main` ブランチに切り替え，リモートの最新状態を取り込む． + +```bash +git checkout main +git pull origin main +``` + +### 作業ブランチの作成 + +最新の `main` から新しいブランチを作成して移動する． + +```bash +git checkout -b feature/new-function +``` + +### 実装とコミット + +- 作業単位（意味のあるまとまり）ごとにコミットする． +- 巨大なコミットは避け，レビューしやすい粒度を心がける． +- AI によるコミットメッセージの生成機能を利用してもよい．ただし，生成されたメッセージは必ず「コミットメッセージ」セクションの書式ルールに合わせて修正すること． + +```bash +git add . +git commit -m "[add] 新機能を実装" +``` + +### リモートへのプッシュ + +作業ブランチをリモートリポジトリへ送信する． + +```bash +git push origin feature/new-function +``` + +### プルリクエスト (PR) の作成 + +GitHub CLI (`gh`) を使用して PR を作成する． + +```bash +gh pr create --title "[add] 新機能を実装" --body "概要" +``` + +- `--title` はコミットメッセージと同じ書式（`[タグ] 内容`）とする． +- 必要に応じて `--reviewer` でレビュワーを指定する． + +### レビューと修正の対応 + +- レビュワーのコメントを確認し，修正が必要な場合はローカルで修正・コミット・プッシュを繰り返す． +- 全ての指摘に対応し，レビュワーから Approve をもらう． + +### マージの実行 + +- マージ方式は「Create a merge commit」を使用する（作業ブランチの全コミット履歴が `main` に残る）． + - 「Squash and merge」「Rebase and merge」は使用しない． + +```bash +gh pr merge --merge --delete-branch +``` + +### ローカル環境のクリーンアップ + +マージ完了後はローカル環境も最新状態に戻し，古いブランチを削除する． + +```bash +git checkout main +git pull origin main +git branch -d feature/new-function +``` + +## コミットメッセージ (Commit Messages) + +### 書式 + +- 書式: `[タグ] 内容` +- 言語: 日本語 +- 句読点: 末尾に句点は不要 + +### タグ一覧 + +| タグ | 用途 | +| --- | --- | +| `[add]` | ファイルや機能の追加 | +| `[update]` | 機能やデータの更新・修正 | +| `[fix]` | バグ修正 | +| `[remove]` | 削除 | +| `[clean]` | 整理，リファクタリング | + +## トラブルシューティング (Troubleshooting) + +### コンフリクトが発生した場合 + +他メンバーの変更と競合した場合の対処手順． + +**main の取り込み** + +作業ブランチに `main` の最新内容をリベースして競合箇所を洗い出す．`merge` ではなく `rebase` を使うことで，履歴が線形に保たれレビューしやすくなる． + +```bash +git checkout main +git pull origin main +git checkout feature/new-function +git rebase main +``` + +**競合の解消** + +エディタ上で `<<<<<<<`，`=======`，`>>>>>>>` で囲まれた箇所を手動で修正する．修正後，以下のコマンドでリベースを続行する． + +```bash +git add [修正したファイル] +git rebase --continue +``` + +全ての競合が解消されたらプッシュする．リベース後は履歴が書き換わるため `-f` オプションが必要になる． + +```bash +git push -f origin feature/new-function +``` + +### 間違えて main にコミットしてしまった場合 + +**まだプッシュしていない場合** + +コミットを取り消し，変更内容を保持したまま新しいブランチへ移動する． + +```bash +git reset --soft HEAD^ +git checkout -b feature/new-function +git commit -m "[add] ..." +``` + +**すでにプッシュしてしまった場合** + +`main` への force push はチーム全員の履歴を壊す危険があるため，自分では対処しない．直ちにチームメンバーに報告し，全員で対応方針を決める． diff --git "a/docs/01_GUIDE/GUIDE_04_\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\345\211\207.txt" "b/docs/01_GUIDE/GUIDE_04_\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\345\211\207.txt" deleted file mode 100644 index 070f242..0000000 --- "a/docs/01_GUIDE/GUIDE_04_\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\345\211\207.txt" +++ /dev/null @@ -1,266 +0,0 @@ -======================================================================== -C# コーディング規則 (C# Coding Style Guide) -======================================================================== - -1. 基本方針 (Basic Policy) ------------------------------------------------------------------------- -Microsoft の C# コーディング規則および .NET ランタイム コーディングガイド -ラインを基本とし，チーム内での一貫性を最優先とする． -本規則に明記されていない事項は Microsoft 公式ガイドラインに従う． -※ 書式・記述スタイルの基準は `GUIDE_01_ドキュメント作成ガイド.txt` を参照する． - - -2. フォーマット (Formatting) ------------------------------------------------------------------------- - -2-1. インデント - ・半角スペース4つを使用する．タブ文字は使用しない． - ・継続行は，開き括弧に揃えるか，ハンギングインデント（スペース4つ追加）とする． - ・例: - - // 開き括弧に揃える - var result = SomeMethod(argOne, argTwo, - argThree, argFour); - - // ハンギングインデント - var result = SomeMethod( - argOne, argTwo, - argThree, argFour); - -2-2. 波括弧 (Braces) - ・開き波括弧「{」は，宣言と同じ行に記述する（K&R スタイル）． - ・例: - - namespace TIASshot { - internal class MotorController { - public void Start() { - if (IsRunning) { - ... - } - } - } - } - - ・単文の `if` / `for` 等でも，必ず波括弧を付ける． - - NG: `if (isActive) return;` - - OK: `if (isActive) { return; }` - -2-3. 1行の最大文字数 - ・120文字を目安とする．超える場合は適切な位置で改行する． - -2-4. 空行 - ・クラス定義の間: 2行空ける． - ・メソッド定義の間: 1行空ける． - ・メソッド内の論理的なまとまりの区切り: 1行空ける（使いすぎに注意）． - -2-5. 文字コード - ・UTF-8（BOM なし）を使用する． - - -3. 命名規則 (Naming Conventions) ------------------------------------------------------------------------- - -3-1. 一覧 - - ■ クラス・構造体・列挙型・デリゲート - ・スタイル: PascalCase - ・例: `CameraBase`，`MotorController`，`DeviceStatus` - - ■ インターフェース - ・スタイル: 「I」プレフィックス + PascalCase - ・例: `ICamera`，`IDeviceControl` - - ■ メソッド・イベント・プロパティ - ・スタイル: PascalCase - ・例: `Connect()`，`GetDataName()`，`IsCalibrating` - - ■ ローカル変数・引数 - ・スタイル: camelCase - ・例: `cameraList`，`saveFolder`，`numImages` - - ■ プライベートフィールド - ・スタイル: アンダースコア + camelCase - ・例: `_camera`，`_isLightOn`，`_calibrating` - - ■ 定数・static readonly フィールド（公開） - ・スタイル: PascalCase - ・例: `MaxSpeed`，`DefaultPort`，`AppName` - ※ 既存コードの `UPPER_SNAKE_CASE`（例: `APP_NAME`）は互換性のため許容するが， - 新規定義は `PascalCase` に統一する． - - ■ 非同期メソッド - ・スタイル: PascalCase + `Async` サフィックス - ・例: `ConnectAsync()`，`SaveImagesAsync()`，`LoadConfigAsync()` - - ■ 列挙型メンバー - ・スタイル: PascalCase - ・例: `DeviceStatus.Connected`，`CaptureMode.Single` - -3-2. 命名の原則 - ・意味のある名前を付け，略語は最小限にする． - - NG: `d`，`tmp`，`val` - - OK: `distance`，`temperature`，`motorValue` - ・ループカウンタ等，スコープが極めて狭い場合のみ `i`，`j`，`x`，`y` を許容する． - ・bool 型のプロパティ・変数は `Is`，`Has`，`Can` 等の接頭辞を付ける． - - 例: `IsConnected`，`HasObstacle`，`CanCapture` - - -4. using ディレクティブの規則 (Using Directives) ------------------------------------------------------------------------- - -4-1. 順序 - 以下の順序で記述し，グループ間に1行空ける． - - 1. System 名前空間（`System`，`System.Collections.Generic` 等） - 2. サードパーティライブラリ（`OpenCvSharp`，`TIS.Imaging` 等） - 3. プロジェクト内名前空間 - - ・例: - - using System; - using System.Collections.Generic; - using System.IO; - - using OpenCvSharp; - - using TIASshot.Camera; - -4-2. スタイル - ・不要な `using` は削除する． - ・`using static` は，同一クラスのメンバーを多用する場合のみ許容する． - - -5. 型の使用規則 (Type Usage) ------------------------------------------------------------------------- - -5-1. var の使用 - ・右辺に型名が明示されている場合は `var` を使用する． - - OK: `var list = new List();` - - OK: `var controller = new MotorController();` - ・右辺から型が読み取れない場合は明示的な型を使用する． - - NG: `var result = GetResult();`（戻り値の型が不明確） - - OK: `XmlNode result = doc.SelectSingleNode("//Config");` - -5-2. null 許容参照型 (Nullable Reference Types) - ・`null` との比較は `is null` / `is not null` を使用する． - - NG: `if (value == null)` - - OK: `if (value is null)` - ・null 合体演算子（`??`，`??=`）や null 条件演算子（`?.`，`?[]`）を積極的に活用する． - - -6. コーディングルール (Coding Rules) ------------------------------------------------------------------------- - -6-1. 文字列 - ・文字列の組み立てには文字列補間（`$"..."`）を使用する． - - NG: `"Speed: " + speed.ToString()` - - OK: `$"Speed: {speed}"` - ・定数文字列は `const string` または `static readonly string` で定義する． - -6-2. 例外処理 - ・裸の `catch (Exception)` は極力避け，具体的な例外クラスを指定する． - - NG: `catch (Exception) { }` - - OK: `catch (ArgumentException ex) { ... }` - ・例外を握りつぶす場合（空の catch 節）は，必ず理由をコメントで明記する． - -6-3. リソース管理 - ・`IDisposable` を実装するオブジェクトは `using` 文で管理する． - ・例: - - using (var reader = new StreamReader(csvFile)) { - while (!reader.EndOfStream) { - ... - } - } - -6-4. マジックナンバーの禁止 - ・意味のある数値や文字列は定数として定義する． - - NG: `Thread.Sleep(500);` - - OK: - const int SensorIntervalMs = 500; - Thread.Sleep(SensorIntervalMs); - -6-5. readonly の使用 - ・コンストラクタ以降に値が変わらないフィールドは `readonly` を付ける． - - NG: `private float _updateRate;`（コンストラクタで1度だけ代入する場合） - - OK: `private readonly float _updateRate;` - ・`static readonly` はクラス定数（`const` にできない参照型など）に使用する． - -6-6. プロパティ vs 公開フィールド - ・`public` フィールドは原則定義しない．外部に公開する値はプロパティを使用する． - - NG: `public string DeviceName;` - - OK: `public string DeviceName { get; protected set; }` - ・外部から読み取りのみ許可する場合は `get` のみ，または `{ get; private set; }` とする． - -6-7. アクセス修飾子 - ・アクセス修飾子は必ず明示する（省略しない）． - - NG: `class Config { ... }` - - OK: `internal static class Config { ... }` - -6-8. UI スレッド - ・ワーカースレッドから UI 操作を行う場合は `InvokeRequired` を確認してから - `Invoke` / `BeginInvoke` を使用する． - ・例: - - public void ShowMessage(string msg) { - if (InvokeRequired) { - Invoke((MethodInvoker)delegate { ShowMessage(msg); }); - return; - } - txtMessage.Text = msg; - } - - -7. ファイル構成 (File Structure) ------------------------------------------------------------------------- -1つの C# ファイル内は，以下の順序で記述する． - - 1. using ディレクティブ - 2. namespace 宣言 - 3. クラス定義（フィールド → プロパティ → コンストラクタ → メソッド） - -・例: - - using System; - using System.IO; - - namespace TIASshot { - internal class MotorController { - // フィールド - private bool _isRunning = false; - - // プロパティ - public bool IsRunning => _isRunning; - - // コンストラクタ - public MotorController() { - ... - } - - // メソッド - public void Start() { - ... - } - } - } - - -8. ツール設定 (Tooling) ------------------------------------------------------------------------- -コードの品質を自動で維持するため，以下のツールの導入を推奨する． - -■ フォーマッター -・`.editorconfig` に本規則の設定を記述し，チームで共有する（IDE 共通）． -・Visual Studio: Ctrl+K, Ctrl+D でフォーマットを実行する． -・VSCode: C# Dev Kit 拡張機能を導入し，Shift+Alt+F でフォーマットを実行する． - - 保存時自動フォーマット（`editor.formatOnSave: true`）の設定を推奨する． - -■ リンター -・Roslyn Analyzers を使用する（Visual Studio・VSCode 共通で動作する）． - - `Microsoft.CodeAnalysis.NetAnalyzers` パッケージの導入を推奨する． - -■ 型チェック -・Visual Studio・VSCode いずれの場合も，ビルドエラー・警告を全て解消してからコミットする． -・dotnet CLI: `dotnet build` でエラーがないことを確認する． - -※ ツールの具体的な設定や導入手順は `ENV_` カテゴリのドキュメントに記載する． diff --git "a/docs/01_GUIDE/GUIDE_05_\343\202\263\343\203\274\343\203\211\343\202\263\343\203\241\343\203\263\343\203\210\350\246\217\345\211\207.txt" "b/docs/01_GUIDE/GUIDE_05_\343\202\263\343\203\274\343\203\211\343\202\263\343\203\241\343\203\263\343\203\210\350\246\217\345\211\207.txt" deleted file mode 100644 index a066da6..0000000 --- "a/docs/01_GUIDE/GUIDE_05_\343\202\263\343\203\274\343\203\211\343\202\263\343\203\241\343\203\263\343\203\210\350\246\217\345\211\207.txt" +++ /dev/null @@ -1,189 +0,0 @@ -======================================================================== -コードコメント・ドキュメント規則 (Code Comment & Documentation Guide) -======================================================================== - - -1. 基本方針 (Basic Policy) ------------------------------------------------------------------------- -コードの可読性と保守性を高めるため，ファイル・クラス・メソッド・定数それ -ぞれに対して適切な粒度でコメントを記述する． -※ コードの書き方自体の規則は `GUIDE_04_コーディング規則.txt` を参照する． - -・言語: 日本語で記述する． -・句読点: 「，」（全角カンマ）を使用し，文末の句点（「．」「。」）は付けない． - - 列挙が続く場合は「，」で区切る． -・文体: 体言止め，または「〜する」形で統一する． -・更新: コードを変更した場合は，対応するコメントも必ず合わせて更新する． - - コードと乖離したコメントは誤解を招くため，古いまま放置しない． - - -2. コメントの種類と用途 (Comment Types) ------------------------------------------------------------------------- - -2-1. XML ドキュメントコメント (XML Doc Comment) - ・全ての public / protected メソッド・プロパティ・クラスに必ず記述する． - ・トリプルスラッシュ（`///`）を使用する． - - ■ クラス・構造体 - ・書式: - - /// - /// [そのクラスが何を表すかを端的に説明] - /// - internal class ClassName { ... } - - ・例: - - /// - /// カメラの基底クラス - /// - internal abstract class CameraBase { ... } - - ■ メソッド（引数・戻り値あり） - ・書式: - - /// - /// [その処理を端的に説明] - /// - /// [説明] - /// [戻り値の説明] - public ReturnType MethodName(Type argName) { ... } - - ・例: - - /// - /// CSV ファイルから Mat を読み込む - /// - /// 読み込む CSV ファイルパス - /// 読み込んだ Mat，失敗時は null - private Mat LoadMatFromCsv(string csvFile) { ... } - - ■ メソッド（引数・戻り値なし，または自明） - ・1行で記述してよい． - - /// - /// 全モーターを停止する - /// - public void Stop() { ... } - - ■ 例外をスローする可能性がある場合 - ・`` タグを追加する． - - /// - /// 設定ファイルから float 値を取得する - /// - /// 設定キー（例: "Calib/UpdateRate"） - /// float 値 - /// - /// 指定されたキーが存在しない場合 - /// - public static float GetFloat(string param) { ... } - - ■ 廃止予定のメンバー - ・`` タグで代替メンバーを案内し，`[Obsolete]` 属性を付ける． - - /// - /// 画像を保存する - /// - /// 非推奨: SaveImageAsync を使用すること - [Obsolete("SaveImageAsync を使用してください")] - public void SaveImage() { ... } - - ■ オーバーライドしたメンバー - ・基底クラスの doc comment を継承する場合は `` を使用する． - ・改めて説明を書く場合はオーバーライド先に通常の `` を記述する． - - /// - public override bool Connect() { ... } - - ■ 他メンバーへの参照 - ・説明文中で他のクラスやメンバーを参照する場合は `` を使用する． - - /// - /// から設定値を読み込む - /// - public void Load() { ... } - - /// - /// 接続に失敗した場合は を参照すること - /// - 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: /// 画像を保存する． - - OK: /// 画像を保存する - -・「、」「。」を使う - - NG: // 撮影開始時の基準座標をセットする。 - - OK: // 撮影開始時の基準座標をセットする - -・コードをコメントアウトして残す - - NG: //_lucam.StartStopPreview(); - - OK: 不要なコードは削除する（Git 履歴から復元できる） - -・XML doc comment を通常コメントで書く - - NG: // Connect: デバイスに接続する - - OK: /// デバイスに接続する