Kotlinのコメントは、単なる補足ではなく「設計意図を伝えるためのドキュメント」として重要な役割を持ちます。
Kotlinは可読性の高いコードを書くことを前提に設計されているため、コメントの書き方にも Javaとは異なる最適解 があります。
この記事では、
- Kotlinで使えるコメントの種類
- 正しい構文と注意点
- KDocの実務的な書き方
- 「書くべきコメント／書かない方がいいコメント」
- チーム開発での考え方
まで、誤解が起きない形で体系的に解説します。Kotlinで使えるコメントの種類
Kotlinのコメントは次の3種類に分類されます。
| 種類 | 構文 | 主な用途 |
|---|---|---|
| 行コメント | // | 1行の補足、理由説明 |
| ブロックコメント | /* */ | 複数行の説明、注意事項 |
| ドキュメンテーションコメント（KDoc） | /** */ | API・設計意図の説明 |
行コメント（//）
基本構文
// これは行コメントです
val count = 10
// 以降、その行の終わりまでがコメントとして扱われます。
Kotlinで推奨される行コメントの考え方
Kotlinでは、コード自体が何をしているかは読めて当然という前提があります。
そのため、行コメントには次の内容を書くのが望ましいです。
- なぜこの処理が必要なのか
- 仕様・制約・背景
- 将来的な注意点
悪い例（コードの説明）
// countが0より大きいか確認
if (count > 0) {
良い例（理由を書く）
// 0件送信するとサーバー側でエラーになるため除外
if (count > 0) {
「何をしているか」ではなく「なぜそうしているか」これがKotlinにおけるコメントの基本姿勢です。
ブロックコメント（/* ... */）
基本構文
/*
複数行にわたる
コメントを書くことができます
*/
処理のまとまりや、詳細な注意点を説明する際に使用します。
Kotlinのブロックコメントの特徴：ネスト可能
Kotlinのブロックコメントは ネスト（入れ子）可能 です。
/*
外側のコメント
/*
内側のコメント
*/
*/
これはJavaやCとは異なる特徴です。
ネスト可能ゆえの注意点（重要）
ブロックコメントがネスト可能であるため、
- コメントアウト対象のコードや文字列内に
/*が含まれている - 意図せずコメントの対応関係が崩れる
といったケースがあります。
/*
val text = "example /* test */"
*/
このような場合、想定外の位置でコメントが終了する可能性があります。
- 一時的なデバッグ用途では便利
- 大規模なコメントアウトでは注意が必要
という特性を理解して使いましょう。
ドキュメンテーションコメント（KDoc）
KDocとは
KDocはKotlin公式のドキュメントコメント形式で、JavaのJavadocに相当します。
- 公開API
- クラス設計
- 関数の契約（引数・戻り値・例外）
を説明するために使用されます。
基本構文（/** */）
/**
* ユーザーの年齢から成人かどうかを判定します
*
* @param age 年齢（0以上）
* @return 成人ならtrue、未成年ならfalse
*/
fun isAdult(age: Int): Boolean {
return age >= 20
}
/** から始めることで、通常のブロックコメントとは区別されます。
KDocが使われる主な対象
- クラス
- インターフェース
- 関数
- プロパティ
- コンストラクタ
- public / internal API
IDE（IntelliJ IDEA / Android Studio）では、補完時やホバー時に表示されることが一般的です。
よく使われるKDocタグ
代表的なKDocタグは以下の通りです。
| タグ | 説明 |
|---|---|
@param | 引数の説明 |
@return | 戻り値の説明 |
@throws | 発生しうる例外 |
@constructor | コンストラクタの説明 |
@property | プロパティの説明 |
@receiver | 拡張関数のレシーバ |
@see | 関連項目 |
@throws に関する補足
Kotlinはチェック例外を強制しない言語です。
そのため @throws はJavaほど必須ではありません。
ただし、
- Javaと相互運用するAPI
- 利用者に例外仕様を伝えたい場合
には、明示的に書く価値があります。
@property の代表的な使い方
/**
* ユーザー情報を表すデータクラス
*
* @property name ユーザー名
* @property age 年齢
*/
data class User(
val name: String,
val age: Int
)
プライマリコンストラクタ内のプロパティは、このように クラスKDocでまとめて説明するのが一般的です。
Kotlinらしいコメントの思想（重要）
Kotlinでは、次の考え方が特に重要です。
書かない方がよいコメント
- 変数名・関数名をそのまま説明するもの
- 処理内容を逐語的に書いたもの
- 読めば分かること（obvious）
書くべきコメント
- ビジネスルール
- 技術的制約
- なぜこの実装になっているのか
- 将来の拡張・注意点
// レガシーAPIの仕様上、nullが返る可能性がある
val result: String? = legacyApi.call()
コメントアウトの扱い方
一時的なデバッグ
// println(result)
大きなブロックの無効化
/*
sendEmail()
sendSlack()
*/
本番コードに長期間コメントアウトを残すのは避け、不要になったら削除するのが望ましいです。
コメントと命名の関係
Kotlinでは 良い命名が最大のコメント になります。
// 悪い例
val f = true // フラグ
// 良い例
val isUserLoggedIn = true
コメントがないと意味が伝わらない命名は、命名自体を見直すサインです。
実務でのおすすめ運用ルール
- public / internal APIにはKDocを書く
- privateな処理は「理由があるときだけコメント」
- TODO / FIXMEは最小限にし、放置しない
- コメントもコードと同じ頻度でメンテナンスする
// TODO: バリデーション仕様確定後に実装
まとめ
- Kotlinのコメントは3種類（行・ブロック・KDoc）
- ブロックコメントはネスト可能だが注意点あり
- KDocはAPI品質を左右する重要要素
- コメントは「理由・背景」を書く
- 良い命名があればコメントは減らせる
以上、Kotlinのコメントの書き方についてでした。
最後までお読みいただき、ありがとうございました。
