diff --git "a/docs/02_Guide/GUIDE_04_\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/02_Guide/GUIDE_04_\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..2faa119 --- /dev/null +++ "b/docs/02_Guide/GUIDE_04_\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,124 @@ +======================================================================== +コードコメント・ドキュメント規則 (Code Comment & Documentation Guide) +======================================================================== + + +1. 基本方針 (Basic Policy) +------------------------------------------------------------------------ +コードの可読性と保守性を高めるため,ファイル・型・関数・定数それぞれに対して +適切な粒度でコメントを記述する. + +・言語: 日本語で記述する. +・句読点: 「,」(全角カンマ)を使用し,文末の句点(「.」「。」)は付けない + - 列挙が続く場合は「,」で区切る +・文体: 体言止め,または「〜する」形で統一する + + +2. コメントの種類と用途 (Comment Types) +------------------------------------------------------------------------ + +2-1. ファイルドキュメント (File Header Doc Comment) + ・ファイルの先頭に必ず記述する. + ・JSDoc形式(`/** */`)を使用する. + ・書式: + + /** + * [ファイル名(拡張子なし)] + * [ファイルの主な責務を1行で説明] + * [補足情報があれば続けて記述] + */ + + ・例: + + /** + * useJoystick + * ジョイスティック入力を受け取り,座標計算と正規化ベクトルの出力を行うフック + * UI描画に必要な中心点・ノブ位置・半径も合わせて提供する + */ + +2-2. 型・定数ドキュメント (Type & Constant Doc Comment) + ・`export` される型(`type`,`interface`)および定数(`const`)には必ず記述する. + ・JSDoc形式の1行コメント(`/** */`)を直前行に記述する. + ・書式: + + /** [その型・定数が何を表すかを端的に説明] */ + export type / const ... + + ・例: + + /** UI側と共有する最大半径の既定値 */ + export const MAX_DIST = 60; + + /** 2D座標の簡易型 */ + type Point = { x: number; y: number }; + + /** フックが返すUI向けの状態とハンドラ */ + type UseJoystickReturn = { ... }; + +2-3. 関数・コンポーネント・フックドキュメント (Function Doc Comment) + ・`export` される関数,Reactコンポーネント,フックには必ず記述する. + ・JSDoc形式の1行コメント(`/** */`)を直前行に記述する. + ・書式: + + /** [その関数・コンポーネントが何をするかを端的に説明] */ + export const / function ... + + ・例: + + /** 正規化ベクトルの出力とUI用の座標を提供するフック */ + export const useJoystick = ... + + /** ポインター入力と描画を結びつけるジョイスティックUI */ + export const Joystick = ... + +2-4. ブロックコメント (Block Comment) + ・関数・コンポーネント内で,処理のまとまりが変わる箇所に記述する. + ・通常の行コメント(`//`)を使用する. + ・書式: + + // [このブロックの処理を端的に説明] + ...処理... + + ・例: + + // 入力開始時の基準座標をセットする + const handleStart = ... + + // 入力座標からベクトルを計算し,半径でクランプして正規化出力する + const handleMove = ... + +2-5. JSXコメント (JSX Comment) + ・JSX内のブロック区切りには `{/* */}` 形式を使用する. + ・例: + + {/* 見た目のみの描画(入力は扱わない) */} + + +2-6. 再エクスポートコメント (Re-export Comment) + ・外部へ再公開する `export { ... }` には1行ドキュメントを付ける. + ・例: + + /** 入力半径の既定値を外部から参照できるように再公開 */ + export { MAX_DIST } from "./useJoystick"; + + +3. 記述しない場合の判断基準 (When to Omit) +------------------------------------------------------------------------ +・ファイル内部でのみ使用し,外部に公開されない型・関数・定数は省略してもよい +・コード自体が自明な場合(変数名で意図が十分伝わる場合)は省略してもよい +・ユニットテストファイルは,テストケース名で意図が伝わる場合は省略してもよい + + +4. NG例 (Anti-patterns) +------------------------------------------------------------------------ +・句点を付ける + - NG: /** ジョイスティックの入力を受け取る. */ + - OK: /** ジョイスティックの入力を受け取る */ + +・「、」「。」を使う + - NG: // 入力開始時の基準座標をセットする。 + - OK: // 入力開始時の基準座標をセットする + +・ファイルヘッダーを通常の行コメントで書く + - NG: // useJoystick: ジョイスティック入力を受け取るフック + - OK: /** \n * useJoystick\n * ジョイスティック入力を受け取るフック\n */