コメント（// と /* */ と /** */）

// 一行コメント — // から行末までがコメントになります。
int count = 0; // 行末コメント — コードの後にも書けます。

/*
  ブロックコメント — /* から */ までの範囲がコメントになります。
  複数行にわたる説明を書くときに使います。
*/

/**
 * Javadoc コメント — /** で始めるブロックコメントです。
 * クラス・メソッド・フィールドの直前に書き、型情報や説明を記述します。
 * {@code javadoc} コマンドで HTML ドキュメントを生成できます。
 *
 * @param value 引数の説明（Javadoc では - を付けない慣習です）
 * @return 戻り値の説明
 * @throws IllegalArgumentException 不正な引数が渡された場合
 */

Javadoc コメントでは、『@』で始まるタグを使って型情報や説明を記述します。Spring Boot プロジェクトでは、@RestController・@Service・@Repository などのクラスや、公開メソッドに Javadoc を書くのが一般的です。IntelliJ IDEA・Eclipse・VS Code（Spring Boot Extension）がホバー表示でドキュメントを提示します。

Spring プロジェクトで見られる特有のコメントパターンがあります。

// @SuppressWarnings と理由コメントの例。
@SuppressWarnings("unchecked")
// Spring の ApplicationContext から取得するため、型安全でないキャストが避けられません。
List<User> users = (List<User>) context.getBean("userList");

Service クラスと Javadoc

UserService.java

package com.example.demo.service;

import com.example.demo.entity.User;
import com.example.demo.repository.UserRepository;
import org.springframework.stereotype.Service;

/**
 * ユーザー情報を管理するサービスクラスです。
 *
 * <p>ユーザーの取得・作成・削除操作を提供します。
 * データアクセスは {@link UserRepository} を通じて行います。</p>
 *
 * @since 1.0
 */
@Service
public class UserService {

    private final UserRepository userRepository;

    // コンストラクタインジェクションを使います。
    // フィールドインジェクション（@Autowired on field）は
    // テスト時にモックを差し込みにくいため使いません（コードレビューの方針）。
    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    /**
     * 指定した ID のユーザーを取得します。
     *
     * @param id ユーザーの一意識別子
     * @return 取得したユーザーオブジェクト
     * @throws com.example.demo.exception.UserNotFoundException ユーザーが存在しない場合
     */
    public User getUser(Long id) {
        return userRepository.findById(id)
                .orElseThrow(() -> new RuntimeException("User not found: " + id));
    }

    /**
     * 新しいユーザーを作成して保存します。
     *
     * @param name  ユーザー名（null・空文字は不可）
     * @param email メールアドレス（null・空文字は不可）
     * @return 保存されたユーザーオブジェクト（ID が自動採番されます）
     * @throws IllegalArgumentException name または email が空の場合
     */
    public User createUser(String name, String email) {
        if (name == null || name.isBlank()) {
            throw new IllegalArgumentException("name must not be blank");
        }
        if (email == null || email.isBlank()) {
            throw new IllegalArgumentException("email must not be blank");
        }

        /*
          User エンティティのコンストラクタでバリデーションを行う設計も考えられますが、
          バリデーションロジックをサービス層に集約する方針を採用しています（ADR-003 参照）。
        */
        User user = new User();
        user.setName(name);
        user.setEmail(email);

        return userRepository.save(user);
    }

    /**
     * 指定した ID のユーザーを削除します。
     *
     * @param id 削除するユーザーの ID
     * @deprecated v2.0 以降は {@link #deleteUser(Long)} を使用してください。
     * @see #deleteUser(Long)
     */
    @Deprecated
    public void removeUser(Long id) {
        deleteUser(id);
    }

    /**
     * 指定した ID のユーザーを削除します。
     *
     * @param id 削除するユーザーの ID
     */
    public void deleteUser(Long id) {
        // TODO: 削除前に関連データの整合性チェックを追加する（#112 参照）。
        userRepository.deleteById(id);
    }
}

RestController と Javadoc

UserController.java

package com.example.demo.controller;

import com.example.demo.entity.User;
import com.example.demo.service.UserService;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

/**
 * ユーザーリソースの REST API エンドポイントを提供するコントローラーです。
 *
 * <p>基本パス: {@code /api/users}</p>
 */
@RestController
@RequestMapping("/api/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    /**
     * GET /api/users/{id} — 指定した ID のユーザーを返します。
     *
     * @param id パスパラメーターから取得するユーザー ID
     * @return ユーザー情報を含む 200 OK レスポンス、存在しない場合は 404 Not Found
     */
    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        User user = userService.getUser(id);
        return ResponseEntity.ok(user);
    }

    /**
     * POST /api/users — 新しいユーザーを作成します。
     *
     * <p>リクエストボディに {@code name} と {@code email} が必要です。</p>
     *
     * @param name  作成するユーザー名
     * @param email 作成するメールアドレス
     * @return 作成されたユーザー情報を含む 201 Created レスポンス
     */
    @PostMapping
    public ResponseEntity<User> createUser(
            @RequestParam String name,
            @RequestParam String email) {
        // デバッグ中: リクエストパラメーターを確認する（本番では削除します）。
        // System.out.println("Creating user: name=" + name + ", email=" + email);
        User created = userService.createUser(name, email);
        return ResponseEntity.status(201).body(created);
    }
}

Spring は Java で書くフレームワークのため、コメントの記法は Java と同じです。一行コメント（『//』）・ブロックコメント（『/* */』）・Javadoc コメント（『/** */』）を使います。Spring Boot プロジェクトでは、@RestController・@Service・@Repository などのクラスや公開メソッドに Javadoc コメントを書くのが一般的です。IntelliJ IDEA などの IDE がホバー表示でドキュメントを提示します。

@Deprecated アノテーションと Javadoc の『@deprecated』タグを組み合わせることで、コンパイラ警告とドキュメントの両方で非推奨を伝えられます。@SuppressWarnings を使う場合は、なぜ警告を抑制しているかの理由を必ずコメントに添えます。

コメントは「何をしているか」ではなく「なぜそうしているか」を書くと効果的です。コードを読めば明らかな処理を逐一コメントで説明するのはノイズになります。変更履歴や削除したコードをコメントとして残す必要もありません。それらはバージョン管理（git）で追跡できます。