Javaの現場で考える「コメントを書くべきか？」問題と、良い書き方・悪い書き方の慣習まとめ
山崎講師
こんにちは。ゆうせいです。
今回はJavaプログラマーの視点から、「プログラムにコメントを書くべきかどうか？」という議論を紹介しつつ、Javaにおけるコメントの書き方の慣習や注意点をわかりやすく解説していきます。
Javaは静的型付けで読みやすい言語と言われていますが、それでもコメントの質によって、可読性が大きく左右されることもありますよね。
あなたは「コメント派」でしょうか？それとも「コメント不要派」？
どちらの立場も見てみましょう！
コメントを書くべき派 vs 書かなくてもよい派
コメントを書くべき派の主張
主な意見：
- コードだけでは伝えられないビジネスロジックの背景を説明できる
- チームでの引き継ぎやレビューがスムーズになる
- 未来の自分のためになる！
例（Java）：
// 顧客IDで検索し、存在しない場合は新規作成する
Customer customer = customerService.findOrCreate(customerId);
コードを見ただけでは、処理の意図が完全に読み取れないこともあるので、「なぜこのメソッドを使っているのか」などを書いておくと安心ですね。
コメントを書かなくてもよい派の主張
よくある意見：
- コードの命名を工夫すればコメント不要
- コメントは放置されがちで腐りやすい
- コメントがコードと乖離することがバグの温床
悪い例：
// ログインチェック
refreshToken(); // 実際には認証トークンの更新
こうした誤解を招くコメントは、ない方がましと考えられます。
古いコメントはむしろ害悪になる場合もありますね。
Javaでコメントを書くときに意識したいこと
1. 「なぜ（Why）」を重視する
良い例：
// 楽天APIはレスポンス順序が保証されないため、明示的にソート
Collections.sort(productList, Comparator.comparing(Product::getId));
「何をしているか」はコードから読めますが、「なぜそれをしているか」はコードだけではわからないことが多いです。
2. JavaDocを積極的に使う
JavaではJavaDoc（ジャバドック）という形式のコメントが標準化されています。
特にパブリックなクラスやメソッドには必須レベルです。
JavaDocの例：
/**
* 指定したIDの顧客を検索し、存在しない場合は新規に作成する。
*
* @param customerId 顧客ID
* @return 顧客オブジェクト
*/
public Customer findOrCreate(String customerId) {
// ...
}
これにより、自動生成されるドキュメントに情報を反映でき、保守性や共有性が格段にアップします！
3. コメントアウトの使い方に注意
// System.out.println("デバッグ用出力");
一時的な無効化は仕方ない場面もありますが、これが大量に残っていると非常に読みにくくなります。
デバッグログはロガー（Loggerクラスなど）で制御するほうがスマートです。
Javaでよく使われるコメントのパターン（一覧）
| コメントの種類 | 説明 | 書き方の例 |
|---|---|---|
| 単一行コメント | 行頭に // を付ける | // キャッシュから取得できなかった場合のみDB検索 |
| ブロックコメント | 複数行に渡る場合 | /* 処理内容の概要をここに記述 */ |
| JavaDocコメント | メソッドやクラスの仕様説明 | /** メソッドの目的や引数・戻り値を説明 */ |
まとめ：どう書くべきか？何を書かないべきか？
書くべきコメント：
- なぜこの処理が必要なのか（背景や理由）
- 特別な制限・仕様への対応（外部API制限など）
- チームメンバーが迷いそうな部分の補足説明
書かない方がいいコメント：
- コードをそのまま文章にしただけのもの
- 曖昧・抽象的すぎる内容（例：「チェック用処理」だけ、など）
- 更新されないことで誤解を招くコメント
今後の学習の指針
これからJavaでのコメントスキルを磨くなら、まず以下を実践してみましょう！
- 「命名を工夫することでコメントを減らせないか？」と問い直す習慣を持つ
- 「この処理はなぜこう書いてあるのか？」をコメントで明記する練習をする
- JavaDocをIDEで自動生成しつつ肉付けする方法をマスターする
さらに余裕があれば、他人のコードレビューを通じて「良いコメント」「悪いコメント」を収集しておくと、自分のスキルにも還元されます！
コメントの良し悪しは、チームの生産性を大きく左右します。
新人エンジニアの皆さんのコメントが、未来のあなたや仲間を助けてくれる存在になりますように！
セイ・コンサルティング・グループの新人エンジニア研修のメニューへのリンク
投稿者プロフィール
- 代表取締役
-
セイ・コンサルティング・グループ株式会社代表取締役。
岐阜県出身。
2000年創業、2004年会社設立。
IT企業向け人材育成研修歴業界歴20年以上。
すべての無駄を省いた費用対効果の高い「筋肉質」な研修を提供します！
この記事に間違い等ありましたらぜひお知らせください。
