java-code-comments

このスキルを使用するタイミング

ユーザーが以下について言及した場合は、必ずこのスキルを使用してください。

• Java コードへのコメント追加
• Java クラス、メソッド、フィールドのドキュメント作成
• JavaDoc コメントの生成
• コードドキュメントの改善
• コードへの注釈またはコメント追加
• Java コードへのコメント追加
• Java ドキュメントコメントの生成
• コードコメント
• コメントの追加

トリガーとなるフレーズの例：

• 「このコードにコメントを追加して」
• 「JavaDoc を生成して」
• 「クラスコメントを追加して」
• 「メソッドコメントを追加して」
• 「フィールドコメントを追加して」
• 「コードコメント」
• 「ドキュメントコメント」
• 「Java コードに一文でコメントを追加して」

このスキルが対応するコンポーネントの種類：

• Controller（REST コントローラー、Spring MVC コントローラー）
• Service（ビジネスサービスのインターフェース）
• ServiceImpl（サービスの実装）
• Application Service（DDD アプリケーションサービス、ドメインロジックの調整）
• Domain Service（DDD ドメインサービス、ドメインのビジネスロジック）
• Feign Service Interface（Feign リモートサービスのインターフェース）
• Mapper（MyBatis マッパー、データアクセス層）
• Model（データモデル、ドメインモデル）
• Entity（JPA エンティティ、データベースエンティティ）
• BO（ビジネスオブジェクト、ビジネスロジックオブジェクト）
• DTO（データ転送オブジェクト）
• VO（値オブジェクト、ビューオブジェクト）
• DAO（データアクセスオブジェクト）
• Repository（Spring Data リポジトリ）
• Configuration（Spring 設定クラス）
• Component（Spring コンポーネント）
• Utility（ユーティリティクラス）
• Exception（カスタム例外クラス）

このスキルの使用方法

重要：ユーザーがコンポーネントの種類や複雑さにかかわらず、Java コードへのコメント追加を希望する場合は、このスキルを起動してください。

ワークフローの概要

このスキルでは、次の体系的な 4 ステップのワークフローに従います。

1. スキャンして理解する - コードベース全体と関連ドキュメントをスキャンし、全体を把握します
2. コンポーネントの種類を確認する - コメントが必要なコンポーネントの種類をユーザーに確認します
3. Todo リストを作成する - クラス名とメソッド名を含む詳細な Todo リストを作成します
4. コメントを追加する - クラスコメント → メソッドコメント → フィールドコメントの順に追加し、完了するたびに Todo リストを更新します

ステップごとの手順

ステップ 1：コードベースをスキャンして理解する

重要：コメントを追加する前に、必ず以下を実施してください。

1. すべての Java ファイルをスキャンする：

   • 現在のディレクトリとサブディレクトリにあるすべての .java ファイルを読みます
   • プロジェクトの構造とアーキテクチャを把握します
   • クラス間の関係（依存関係、継承、コンポジション）を特定します

2. 関連ドキュメントを読む：

   • README.md ファイル
   • API ドキュメント
   • アーキテクチャドキュメント
   • ビジネス要件ドキュメント（利用可能な場合）

3. コンテキストを理解する：

   • 各クラスは何をするのか
   • 各メソッドの目的は何か
   • フィールドは何を表すのか
   • コンポーネント同士はどのように連携するのか

4. パターンを特定する：

   • プロジェクトで使用されている命名規則
   • 既存のコメントスタイル（ある場合）
   • アーキテクチャパターン（MVC、DDD など）
   • フレームワークの使用状況（Spring、MyBatis など）

出力：コードベースの理解内容を、以下を含めて要約します。

• プロジェクト構造の概要
• 特定した主要コンポーネント
• 検出したアーキテクチャパターン
• 既存ドキュメントの状況

ステップ 2：コンポーネントの種類を確認する

重要：コメントが必要なコンポーネントの種類を、必ずユーザーに確認してください。

一般的な Java コンポーネントの種類のチェックリストを提示し、ユーザーに選択してもらいます。

请确认需要进行代码注释的分类（可多选）：
- [ ] Controller（控制器）
- [ ] Service（服务接口）
- [ ] ServiceImpl（服务实现）
- [ ] Application Service（应用服务，DDD架构）
- [ ] Domain Service（领域服务，DDD架构）
- [ ] Feign Service Interface（Feign远程服务接口）
- [ ] Mapper（数据访问层）
- [ ] Model（数据模型）
- [ ] Entity（实体类）
- [ ] BO（业务对象）
- [ ] DTO（数据传输对象）
- [ ] VO（视图对象）
- [ ] DAO（数据访问对象）
- [ ] Repository（仓储）
- [ ] Configuration（配置类）
- [ ] Component（组件类）
- [ ] Utility（工具类）
- [ ] Exception（异常类）
- [ ] 其他（请 specify）

コメントの種類についても確認してください。

• クラスコメント
• メソッドコメント
• フィールドコメント

次のステップに進む前に、ユーザーの確認を待ってください。

ステップ 3：ToDo リストの作成

重要：ユーザーがコンポーネントの種類を確認した後、詳細な ToDo リストを作成してください。

ユーザーが選択したコンポーネントの種類ごとに、次の手順を実行してください。

1. コードベースをスキャンして、該当するすべてのクラスを見つけます。

   • ファイル検索を使用して、パターンに一致するクラスを見つけます（例：*Controller.java、*Service.java）
   • コメントが必要なクラスをすべて一覧表示します

2. 各クラスについて、次の項目を特定します。

   • クラス名
   • コメントが必要なメソッド
   • コメントが必要なフィールド

3. 次の形式で構造化された ToDo リストを作成します。

## Todo List: Java Code Comments

### Controller 层
- [ ] UserController
  - [ ] 类注释
  - [ ] createUser() - 方法注释
  - [ ] updateUser() - 方法注释
  - [ ] deleteUser() - 方法注释
  - [ ] userId - 属性注释

### Service 层
- [ ] UserService
  - [ ] 类注释
  - [ ] findUserById() - 方法注释
  - [ ] saveUser() - 方法注释

### ServiceImpl 层
- [ ] UserServiceImpl
  - [ ] 类注释
  - [ ] findUserById() - 方法注释
  - [ ] saveUser() - 方法注释

### Mapper 层
- [ ] UserMapper
  - [ ] 类注释
  - [ ] selectById() - 方法注释

### Model/Entity 层
- [ ] User
  - [ ] 类注释
  - [ ] id - 属性注释
  - [ ] username - 属性注释
  - [ ] email - 属性注释

重要：

• コンポーネントの種類ごとに整理します
• 選択した種類に一致するクラスをすべて一覧表示します
• コメントが必要なメソッドとフィールドをすべて含めます
• 進捗管理にチェックボックスを使用します

ステップ 4：コメント作業の実行

重要：指定された順序でコメントを追加し、完了するたびに ToDo リストを更新してください。

実行順序：

1. クラスレベルのコメント（类注释）— 最初
2. メソッドレベルのコメント（方法注释）— 2 番目
3. フィールドレベルのコメント（属性注释）— 3 番目

ToDo リストの各項目について：

1. 一度に 1 つのクラスを処理します。

   • クラスレベルのコメントから始めます
   • 次に、そのクラスのすべてのメソッドを処理します
   • 最後に、そのクラスのすべてのフィールドを処理します
   • クラスの処理が完了したら、ToDo リストを更新します

2. クラスレベルのコメント形式（標準 JavaDoc）：

   /**
    * [Class description]
    * 
    * <p>This class [purpose and responsibility]
    * 
    * @author [Author name if available]
    * @since [Version or date if available]
    */
   public class UserController {
   

   クラスレベルのコメント形式（Java コーディング規約 — 厳格）：

   /**
    * <p>[Class description]</p>
    * 
    * <p>This class [purpose and responsibility]</p>
    * 
    * @author [Author name if available]
    * @since [Version or date if available]
    */
   public class UserController {
   

   クラスレベルのコメント形式（Java コーディング規約 — 厳格、用途別）：

   アプリケーションサービス：

   /**
    * {服务名称}应用服务
    *
    * <p>{详细描述服务的业务功能、职责和应用场景}</p>
    * <p>主要功能包括:</p>
    * <ul>
    *   <li>{功能点1}</li>
    *   <li>{功能点2}</li>
    *   <li>{功能点3}</li>
    * </ul>
    *
    * @author system
    * @since 2025-01-21
    */
   public class UserApplicationService {
   

   ドメインサービス：

   /**
    * {服务名称}领域服务
    *
    * <p>{详细描述服务的领域职责和业务逻辑}</p>
    * <p>主要功能包括:</p>
    * <ul>
    *   <li>{功能点1}</li>
    *   <li>{功能点2}</li>
    * </ul>
    *
    * @author system
    * @since 2025-01-21
    */
   public class UserDomainService {
   

   Feign サービスインターフェース：

   /**
    * {服务名称}Feign远程服务接口
    *
    * <p>通过Feign调用{目标服务}的远程接口</p>
    * <p>主要功能:</p>
    * <ul>
    *   <li>{接口功能1}</li>
    *   <li>{接口功能2}</li>
    * </ul>
    *
    * @author system
    * @since 2025-01-21
    */
   public interface UserFeignService {
   

3. メソッドレベルのコメント形式（標準 JavaDoc）：

   /**
    * [Method description]
    * 
    * @param [paramName] [parameter description]
    * @return [return value description]
    * @throws [ExceptionType] [exception description]
    */
   public UserDTO createUser(@RequestBody UserCreateRequest request) {
   

   メソッドレベルのコメント形式（Java コーディング規約 — 厳格）：

   /**
    * <p>[Method description]</p>
    * 
    * <p>[Detailed description]</p>
    * 
    * @param [paramName] [paramType] [parameter description]
    * @return [returnType] [return value description]
    * @exception [full.package.ExceptionType] [exception description]
    */
   public UserDTO createUser(@RequestBody UserCreateRequest request) {
   

4. フィールドレベルのコメント形式（標準 JavaDoc）：

   /**
    * [Field description]
    */
   private Long userId;
   

   フィールドレベルのコメント形式（Java コーディング規約 — 厳格）：

   /**
    * <p>[Field description]</p>
    * 
    * <p>[Detailed description if needed]</p>
    */
   private Long userId;
   

5. 各クラスの処理が完了したら：

   • ToDo リストを更新し、完了した項目に [x] を付けます
   • 進捗をユーザーに提示します
   • 次のクラスに進みます

進捗更新の例：

## Progress Update

✅ Completed: UserController
  - [x] 类注释
  - [x] createUser() - 方法注释
  - [x] updateUser() - 方法注释
  - [x] deleteUser() - 方法注释
  - [x] userId - 属性注释

🔄 In Progress: UserService
  - [x] 类注释
  - [ ] findUserById() - 方法注释
  - [ ] saveUser() - 方法注释

コメントの品質ガイドライン

重要：コメント形式の規約

このスキルでは、次の 2 つの規約に従います。

1. 標準 JavaDoc（デフォルト）：javadoc-standards.md（このスキル内）を参照してください
2. Java コーディング規約（厳格）：java-coding-standards.md（このスキル内）を参照してください

Java コーディング規約では、次のことが求められます。

• 説明は <p> タグで囲む必要があります：<p>description</p>
• パラメーターの型を宣言する必要があります：@param paramName paramType description
• 戻り値の型を宣言する必要があります：@return returnType description
• 例外の型は完全修飾名で宣言する必要があります：@exception java.lang.Exception description

クラスコメントには、次の内容を含めてください。

• クラスの目的を明確に説明します（Java コーディング規約に従う場合は <p> タグで囲みます）
• 主な責務
• 使用例（複雑な場合）
• 関連するクラスまたはコンポーネント
• 作成者とバージョン（情報がある場合）

メソッドコメントには、次の内容を含めてください。

• メソッドの動作を明確に説明します（Java コーディング規約に従う場合は <p> タグで囲みます）
• 説明と型を付けたすべてのパラメーター
• 型を含む戻り値の説明
• スローされる可能性のある例外（完全修飾名を付けます）
• 使用例（複雑なメソッドの場合）
• 副作用（ある場合）

フィールドコメントには、次の内容を含めてください。

• フィールドが表す内容を明確に説明します（Java コーディング規約に従う場合は <p> タグで囲みます）
• データ型と制約（該当する場合）
• デフォルト値（該当する場合）
• 他のフィールドとの関係（該当する場合）

ベストプラクティス

1. 簡潔かつ完全に記述する：コメントは冗長にならないよう、明確で有益な内容にします
2. JavaDoc 形式を使用する：標準的な JavaDoc の規約に従います
3. 一貫性を保つ：すべてのコメントで一貫したスタイルを使用します
4. TODO リストを更新する：各項目の完了後は、必ず TODO リストを更新します
5. 一度に 1 つのクラスを扱う：次のクラスに進む前に、1 つのクラス全体を処理します
6. 既存のコードを尊重する：コードのロジックは変更せず、コメントのみを追加します
7. コンテキストを考慮する：コメントは実際のコードの動作とビジネスコンテキストを反映する必要があります

コメントテンプレート

コンポーネントの種類に応じて、templates/ ディレクトリ内の適切なテンプレートを使用します：

• templates/controller-comment-template.md - Controller クラスのコメント
• templates/service-comment-template.md - Service インターフェースのコメント
• templates/serviceimpl-comment-template.md - Service 実装のコメント
• templates/application-service-comment-template.md - Application Service のコメント（DDD）
• templates/domain-service-comment-template.md - Domain Service のコメント（DDD）
• templates/feign-service-comment-template.md - Feign Service インターフェースのコメント
• templates/mapper-comment-template.md - Mapper のコメント
• templates/entity-comment-template.md - Entity クラスのコメント
• templates/dto-comment-template.md - DTO クラスのコメント

コメント規約の参考資料

注：すべての参考資料は、このスキルのディレクトリ構成内にあります。

• 標準 JavaDoc：reference/javadoc-standards.md を参照してください（ローカル参考資料）
• Java コーディング規約（厳格な形式）：reference/java-coding-standards.md を参照してください（ローカル参考資料）

Java コーディング規約の形式を使用する場合：

• プロジェクトが明示的に《JAVA 编程规范》に準拠している場合
• プロジェクトで、説明に <p> タグを使用する厳格な形式が求められる場合
• コメント内でパラメーターと戻り値の型を明示する必要がある場合

例

完全な例については、examples/ ディレクトリを参照してください：

• examples/controller-example.md - Controller のコメント例
• examples/service-example.md - Service のコメント例
• examples/entity-example.md - Entity のコメント例
• examples/full-workflow-example.md - ワークフロー全体の例

キーワード

英語のキーワード： java, code comments, javadoc, documentation, class comments, method comments, field comments, code annotation, code documentation, java documentation, add comments, generate comments, document code, code comments java, java code comments, controller comments, service comments, mapper comments, entity comments, dto comments

中国語のキーワード（中文关键词）： Java 代码注释, 添加注释, 生成注释, 代码注释, 文档注释, JavaDoc, 类注释, 方法注释, 属性注释, 字段注释, 给代码添加注释, 代码文档, Java 文档, 注释生成, 一句话添加注释, Controller 注释, Service 注释, Mapper 注释, Entity 注释, DTO 注释, 代码注解

よくある落とし穴（Gotchas）

1. バージョンの互換性：フレームワークのバージョンと依存ライブラリの互換性に注意してください。バージョンによって API に違いがある場合があります
2. 設定ファイルの形式：設定ファイルの形式エラーは最もよくある問題です。エディターの構文チェックを使用することをおすすめします
3. 環境変数：必要な環境変数がすべて正しく設定されていることを確認し、機密情報をハードコードしないでください
4. 依存関係の競合：複数のバージョンが共存する場合は依存関係の競合に注意し、lock ファイルを使用してバージョンを固定してください
5. パフォーマンス上の落とし穴：大量のデータを扱う場合はパフォーマンスの最適化に注意し、N+1 クエリなどのよくある問題を回避してください