diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..13edaea --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,48 @@ +# CLAUDE.md + +このプロジェクトでは `docs/01_GUIDE/` 以下に定義されたルールを必ず遵守すること。 +各ファイルの詳細はリンク先を参照する。 + +--- + +## ドキュメント作成 + +[GUIDE_01_ドキュメント作成ガイド.txt](docs/01_GUIDE/GUIDE_01_ドキュメント作成ガイド.txt) + +テキストドキュメントの書式全般を定義する。句読点は「,」「.」を使用し「、」「。」は使わない。 +見出し階層(大見出し・中見出し・■・・・・-)や空行ルールに従うこと。 + +--- + +## ファイル命名 + +[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) + +ブランチ命名(`feature/`・`fix/`・`refactor/` 等),コミットメッセージのタグ(`[add]`・`[update]`・`[fix]`・`[remove]`・`[clean]`),PR フロー(必ず PR 経由でマージ,直プッシュ禁止)を定義する。 + +--- + +## コーディング規則 + +[GUIDE_04_コーディング規則.txt](docs/01_GUIDE/GUIDE_04_コーディング規則.txt) + +Python コードの書き方を定義する。PEP 8 準拠,snake_case / PascalCase / UPPER_SNAKE_CASE の使い分け, +型ヒント必須,`from ... import *` 禁止,マジックナンバー禁止など。 + +--- + +## コードコメント規則 + +[GUIDE_05_コードコメント規則.txt](docs/01_GUIDE/GUIDE_05_コードコメント規則.txt) + +コメント・docstring の書き方を定義する。モジュール・クラス・公開関数には docstring 必須。 +コメントは日本語,句読点は「,」を使用,文末の「.」は付けない。Google スタイルの docstring を使用する。 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" new file mode 100644 index 0000000..8dafd98 --- /dev/null +++ "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" @@ -0,0 +1,146 @@ +======================================================================== +ドキュメント作成ガイドライン (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_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" new file mode 100644 index 0000000..a1ff832 --- /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\345\221\275\345\220\215\350\246\217\345\211\207.txt" @@ -0,0 +1,68 @@ +======================================================================== +ドキュメント管理・ファイル命名規則 (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" new file mode 100644 index 0000000..4fb7537 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_03_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.txt" @@ -0,0 +1,145 @@ +======================================================================== +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_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" new file mode 100644 index 0000000..1bce5cf --- /dev/null +++ "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" @@ -0,0 +1,230 @@ +======================================================================== +Python コーディング規則 (Python Coding Style Guide) +======================================================================== + +1. 基本方針 (Basic Policy) +------------------------------------------------------------------------ +PEP 8 を基本とし,チーム内での一貫性を最優先とする. +本規則に明記されていない事項は PEP 8 に従う. +※ 書式・記述スタイルの基準は `GUIDE_01_ドキュメント作成ガイド.txt` を参照する. + + +2. フォーマット (Formatting) +------------------------------------------------------------------------ + +2-1. インデント + ・半角スペース4つを使用する.タブ文字は使用しない. + ・継続行は,開き括弧に揃えるか,ハンギングインデント(スペース4つ追加)とする. + ・例: + + # 開き括弧に揃える + result = some_function(arg_one, arg_two, + arg_three, arg_four) + + # ハンギングインデント + result = some_function( + arg_one, arg_two, + arg_three, arg_four, + ) + +2-2. 1行の最大文字数 + ・79文字を上限とする(PEP 8 準拠). + ・文字列やコメントが長くなる場合は,括弧による暗黙の行継続を優先する. + ・バックスラッシュ `\` による行継続は極力避ける. + +2-3. 空行 + ・トップレベルの関数・クラス定義の間: 2行空ける. + ・クラス内のメソッド定義の間: 1行空ける. + ・関数内の論理的なまとまりの区切り: 1行空ける(使いすぎに注意). + +2-4. 文字コード + ・UTF-8 を使用する. + ・エンコーディング宣言(`# -*- coding: utf-8 -*-`)は Python 3 では不要. + + +3. 命名規則 (Naming Conventions) +------------------------------------------------------------------------ + +3-1. 一覧 + + ■ 変数・関数・メソッド・引数 + ・スタイル: snake_case + ・例: `motor_speed`,`calc_distance`,`handle_input` + + ■ 定数 + ・スタイル: UPPER_SNAKE_CASE + ・例: `MAX_SPEED`,`DEFAULT_PORT`,`PIN_MOTOR_LEFT` + + ■ クラス + ・スタイル: PascalCase + ・例: `MotorController`,`SensorReader`,`UltrasonicSensor` + + ■ モジュール(ファイル名) + ・スタイル: snake_case + ・例: `motor_controller.py`,`sensor_reader.py` + + ■ パッケージ(ディレクトリ名) + ・スタイル: 全て小文字,アンダースコアなし(短い名前を推奨) + ・例: `drivers`,`utils`,`config` + + ■ プライベート + ・先頭にアンダースコア1つを付与する. + ・例: `_internal_value`,`_calc_raw_data` + +3-2. 命名の原則 + ・意味のある名前を付け,略語は最小限にする. + - NG: `d`,`tmp`,`val`,`calc`(単体で使用) + - OK: `distance`,`temperature`,`motor_value` + ・ループカウンタ等,スコープが極めて狭い場合のみ `i`,`j`,`x`,`y` を許容する. + ・bool 型の変数は `is_`,`has_`,`can_` 等の接頭辞を付ける. + - 例: `is_connected`,`has_obstacle`,`can_move` + + +4. import の規則 (Import Rules) +------------------------------------------------------------------------ + +4-1. 順序 + 以下の順序で記述し,グループ間に1行空ける. + + 1. 標準ライブラリ(`os`,`sys`,`time` 等) + 2. サードパーティライブラリ(`RPi.GPIO`,`numpy` 等) + 3. プロジェクト内モジュール + + ・例: + + import os + import sys + import time + + import RPi.GPIO as GPIO + + from drivers.motor import MotorController + from sensors.ultrasonic import UltrasonicSensor + +4-2. スタイル + ・1行に1モジュールを記述する. + - NG: `import os, sys` + - OK: `import os` と `import sys` を別行に記述 + ・`from ... import *` は禁止する(名前空間の汚染を防ぐ). + ・`from ... import` で複数の名前を取り込む場合は括弧でまとめる. + + from sensors.ultrasonic import ( + UltrasonicSensor, + TRIGGER_PIN, + ECHO_PIN, + ) + + +5. 型ヒント (Type Hints) +------------------------------------------------------------------------ + +5-1. 方針 + ・関数の引数と返り値には型ヒントを付与する. + ・ローカル変数への型ヒントは,型が自明でない場合のみ付与する. + +5-2. 書式 + ・Python 3.10 以降の記法(`X | None`,`list[int]`)を使用する. + ・例: + + def calc_distance(speed: float, duration: float) -> float: + return speed * duration + + def find_obstacle(sensors: list[UltrasonicSensor]) -> int | None: + ... + + +6. コーディングルール (Coding Rules) +------------------------------------------------------------------------ + +6-1. 比較 + ・`None` との比較は `is` / `is not` を使用する. + - NG: `if value == None:` + - OK: `if value is None:` + ・bool 値との比較は暗黙的に行う. + - NG: `if is_active == True:` + - OK: `if is_active:` + +6-2. 文字列 + ・引用符はダブルクォート `"` で統一する. + ・文字列の組み立てには f-string を使用する. + - NG: `"Speed: " + str(speed)` + - OK: `f"Speed: {speed}"` + +6-3. 例外処理 + ・裸の `except:` は禁止する.必ず例外クラスを指定する. + - NG: `except:` + - OK: `except ValueError:` + ・`except Exception` も極力避け,具体的な例外を捕捉する. + +6-4. with 文 + ・ファイル操作や GPIO のクリーンアップなど,リソース管理には `with` 文を使用する. + ・例: + + with open("config.json", "r") as f: + config = json.load(f) + +6-5. マジックナンバーの禁止 + ・意味のある数値は定数として定義する. + - NG: `time.sleep(0.5)` + - OK: + SENSOR_INTERVAL_SEC = 0.5 + time.sleep(SENSOR_INTERVAL_SEC) + + +7. ファイル構成 (File Structure) +------------------------------------------------------------------------ +1つの Python ファイル内は,以下の順序で記述する. + + 1. ファイルドキュメント(docstring) + 2. import 文 + 3. 定数定義 + 4. クラス定義 / 関数定義 + 5. `if __name__ == "__main__":` ブロック(必要な場合のみ) + +・例: + + """ + motor_controller + モーターの制御を担当するモジュール + """ + + import time + + import RPi.GPIO as GPIO + + from config.pins import PIN_MOTOR_LEFT, PIN_MOTOR_RIGHT + + MAX_SPEED = 100 + DEFAULT_SPEED = 50 + + + class MotorController: + """左右のモーターを制御するクラス""" + + def __init__(self, left_pin: int, right_pin: int) -> None: + ... + + def forward(self, speed: int = DEFAULT_SPEED) -> None: + ... + + + if __name__ == "__main__": + controller = MotorController(PIN_MOTOR_LEFT, PIN_MOTOR_RIGHT) + controller.forward() + + +8. ツール設定 (Tooling) +------------------------------------------------------------------------ +コードの品質を自動で維持するため,以下のツールの導入を推奨する. + +■ フォーマッター +・black: コードの自動整形に使用する. + - 1行の最大文字数は 79 に設定する. + +■ リンター +・flake8 または ruff: スタイル違反や潜在的なバグを検出する. + +■ 型チェッカー +・mypy: 型ヒントの整合性を静的に検証する. + +※ ツールの具体的な設定や導入手順は `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" new file mode 100644 index 0000000..671a5d3 --- /dev/null +++ "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" @@ -0,0 +1,197 @@ +======================================================================== +コードコメント・ドキュメント規則 (Code Comment & Documentation Guide) +======================================================================== + + +1. 基本方針 (Basic Policy) +------------------------------------------------------------------------ +コードの可読性と保守性を高めるため,ファイル・クラス・関数・定数それぞれに対して +適切な粒度でコメントを記述する. +※ コードの書き方自体の規則は `GUIDE_04_コーディング規則.txt` を参照する. + +・言語: 日本語で記述する. +・句読点: 「,」(全角カンマ)を使用し,文末の句点(「.」「。」)は付けない. + - 列挙が続く場合は「,」で区切る. +・文体: 体言止め,または「〜する」形で統一する. +・更新: コードを変更した場合は,対応するコメントも必ず合わせて更新する. + - コードと乖離したコメントは誤解を招くため,古いまま放置しない. + + +2. コメントの種類と用途 (Comment Types) +------------------------------------------------------------------------ + +2-1. ファイルドキュメント (Module Docstring) + ・ファイルの先頭に必ず記述する. + ・トリプルダブルクォート(`""" """`)を使用する. + ・書式: + + """ + [ファイル名(拡張子なし)] + [ファイルの主な責務を1行で説明] + [補足情報があれば続けて記述] + """ + + ・例: + + """ + motor_controller + モーターの制御を担当するモジュール + GPIO を介して左右のモーターの速度・方向を制御する + """ + +2-2. クラスドキュメント (Class Docstring) + ・全てのクラスに記述する. + ・クラス定義の直後にトリプルダブルクォートで記述する. + ・書式: + + class ClassName: + """[そのクラスが何を表すかを端的に説明]""" + + ・複数行が必要な場合: + + class ClassName: + """ + [そのクラスが何を表すかを端的に説明] + [補足情報] + """ + + ・例: + + class MotorController: + """左右のモーターを GPIO 経由で制御するクラス""" + +2-3. 関数・メソッドドキュメント (Function Docstring) + ・公開関数・メソッドには必ず記述する. + ・Google スタイルの docstring を使用する. + ・書式: + + def function_name(arg1: type, arg2: type) -> return_type: + """[その関数が何をするかを端的に説明] + + Args: + arg1: [説明] + arg2: [説明] + + Returns: + [返り値の説明] + """ + + ・引数・返り値がない,または自明な場合は1行で省略してよい. + + def stop(self) -> None: + """全モーターを停止する""" + + ・例外をスローする可能性がある場合は `Raises` セクションを付ける. + + def set_speed(self, speed: int) -> None: + """モーターの速度を設定する + + Args: + speed: 0〜100 の範囲の速度値 + + Raises: + ValueError: speed が 0〜100 の範囲外の場合 + """ + + ・廃止予定のものには非推奨であることを明記し,代替を示す. + + def old_method(self) -> None: + """非推奨: new_method を使用すること""" + + ・例: + + def calc_distance(speed: float, duration: float) -> float: + """速度と時間から距離を計算する + + Args: + speed: 移動速度 (m/s) + duration: 経過時間 (s) + + Returns: + 移動距離 (m) + """ + return speed * duration + +2-4. 定数ドキュメント (Constant Comment) + ・公開される定数にはインラインコメント(`#`)を直前行に記述する. + ・書式: + + # [その定数が何を表すかを端的に説明] + CONSTANT_NAME = value + + ・例: + + # UI側と共有する最大速度の既定値 + MAX_SPEED = 100 + + # 超音波センサーの測定間隔 (秒) + SENSOR_INTERVAL_SEC = 0.5 + +2-5. ブロックコメント (Block Comment) + ・関数・メソッド内で,処理のまとまりが変わる箇所に記述する. + ・`#` + 半角スペースを使用する. + ・書式: + + # [このブロックの処理を端的に説明] + ...処理... + + ・例: + + # 入力値を正規化する + normalized = raw_value / MAX_VALUE + + # モーターに速度を反映する + GPIO.output(self._pin, normalized) + +2-6. タスクコメント (Task Comment) + ・後で対応が必要な箇所に記述し,担当者と内容を明記する. + ・`#` + 半角スペースを使用し,以下のタグで種別を区別する. + ・書式: + + # [タグ]([担当者名]): [内容] + + ■ タグ定義: + - TODO : 将来的に実装・対応が必要な箇所 + - FIXME : 既知のバグや不具合があり修正が必要な箇所 + - HACK : 意図的な暫定対応であり,本来あるべき実装ではない箇所 + + ・例: + + # TODO(yamada): タイムアウト処理を実装する + # FIXME(tanaka): 距離が負になるケースでクラッシュする + # HACK(suzuki): API仕様確定まで固定値で代替している + + ・注意: + - 「いつか直す」ではなく,必ずタスク管理ツールとセットで運用する + - FIXME はリリース前に必ず解消する + - HACK は技術的負債として定期的に見直す + + +3. 記述しない場合の判断基準 (When to Omit) +------------------------------------------------------------------------ +・ファイル内部でのみ使用し,外部に公開されない関数・定数は省略してもよい +・コード自体が自明な場合(変数名で意図が十分伝わる場合)は省略してもよい +・ユニットテストファイルは,テストケース名で意図が伝わる場合は省略してもよい + + +4. NG例 (Anti-patterns) +------------------------------------------------------------------------ +・句点を付ける + - NG: """ジョイスティックの入力を受け取る.""" + - OK: """ジョイスティックの入力を受け取る""" + +・「、」「。」を使う + - NG: # 入力開始時の基準座標をセットする。 + - OK: # 入力開始時の基準座標をセットする + +・コードをコメントアウトして残す + - NG: # old_handler = lambda: ... + - OK: 不要なコードは削除する(Git履歴から復元できる) + +・docstring を通常のコメントで書く + - NG: # motor_controller: モーターの制御を担当するモジュール + - OK: + """ + motor_controller + モーターの制御を担当するモジュール + """