Kotlinにおけるコメントアウトは、単なる「コードの無効化手段」ではありません。
可読性・保守性・チーム開発効率を左右する重要な要素です。
本記事では、
- Kotlinのコメントの種類
- KDoc（ドキュメントコメント）の正しい使い方
- 実務でのベストプラクティス
- よくある誤解と注意点
を正確性重視で体系的に解説します。
目次
Kotlinのコメントアウトは3種類ある
Kotlinには、用途の異なる3種類のコメントがあります。
行コメント（単一行コメント）
// これは行コメントです
val count = 10 // 行末にも書けます
特徴
//から行末までがコメント- 最も頻繁に使われる形式
- 短い補足説明や一時的な無効化に適している
主な用途
- 処理の意図の補足
- デバッグ時の一時コメントアウト
- TODOメモ
ブロックコメント（複数行コメント）
/*
複数行に
またがる
コメント
*/
特徴
/*～*/で囲まれた範囲がコメント- 複数行をまとめてコメントアウトできる
- Kotlinではブロックコメントのネスト（入れ子）が可能
/*
外側のコメント
/*
内側のコメント
*/
*/
これはJavaとの明確な違いで、既存のブロックコメントを含むコードを安全に無効化できるという利点があります。
※なお、文字列リテラル（" " や """ """）内の /* はコメントとしては扱われません。
ドキュメントコメント（KDoc）
/**
* ユーザー名を取得する
*
* @param userId ユーザーID
* @return ユーザー名
*/
fun getUserName(userId: Int): String {
return "Taro"
}
/** から始まるコメントは KDoc として扱われます。
これはKotlin公式のドキュメント形式で、Javadocに相当します。
KDoc（Kotlinドキュメントコメント）とは何か
KDocは、人間向けの説明とツール向けの構造を両立したコメントです。
KDocの主な特徴
- IDEの補完・クイックドキュメントに表示される
- APIの仕様・意図を明確にできる
- Dokkaなどのツールと組み合わせてドキュメント生成が可能
よく使われるKDocタグ
| タグ | 用途 |
|---|---|
@param | 引数の説明 |
@return | 戻り値の説明 |
@throws | 例外の説明 |
@property | プロパティの説明 |
@constructor | コンストラクタの説明 |
@sample | 使用例コードへの参照 |
/**
* ユーザーを表すデータクラス
*
* @property id ユーザーID
* @property name ユーザー名
*/
data class User(
val id: Int,
val name: String
)
※タグの表示や反映のされ方は、IDE設定やドキュメント生成ツールによって多少差が出る場合があります。
TODO / FIXME などの特別なコメント
IntelliJ IDEA や Android Studio では、特定のキーワードを含むコメントが認識されます。
// TODO: エラーハンドリングを追加する
// FIXME: nullチェックが不完全
// NOTE: パフォーマンスに注意
ポイント
TODOやFIXMEは多くの環境で標準的に検出される- TODOビューで一覧管理できる
- 検出対象のキーワードはIDE設定でカスタマイズ可能
NOTEなどは環境や設定によって扱いが異なる場合がある
実務でのコメントの書き方
悪い例（コードの内容をそのまま説明）
// iに1を足す
i++
→ コードを見れば分かることはコメントしない
良い例（「なぜ」を説明）
// バックエンド仕様によりnullが返る可能性がある
val name: String? = response.name
コメントは「何をしているか」ではなく「なぜそうしているか」を書くのが原則です。
コメントアウトでよくある問題点
コメントアウトされたコードを放置する
// val result = oldLogic()
- 不要になったコードは削除する
- コメントアウトは一時的な手段に留める
コメントと実装の乖離
// ユーザーIDを取得
val userId = user.name
- リファクタ時にコメントを更新し忘れると、最も危険な状態になる
- コード変更時はコメントも必ず見直す
KDocと実装の不整合
- 引数名変更後に
@paramを修正していない - 返り値仕様変更を反映していない
IDEでよく使うコメント関連ショートカット
| 操作 | ショートカット |
|---|---|
| 行コメント切替 | Ctrl + / |
| ブロックコメント切替 | Ctrl + Shift + / |
| KDoc雛形生成 | /** + Enter |
※macOSやカスタムキーマップでは異なる場合があります。
Kotlinらしい考え方：コメントを減らす書き方
Kotlinは、コード自体が意図を表現しやすい言語です。
// ❌ コメントに頼る
if (x == null) {
return
}
// ✅ Kotlinのイディオム
x ?: return
理想的な状態は、
- コードで8割を語る
- コメントで残り2割（理由・背景）を補足する
まとめ
- Kotlinのコメントは「行・ブロック・KDoc」の3種類
- ブロックコメントはネスト可能
- KDocは設計意図・API仕様の共有に不可欠
- TODO / FIXME を使うと保守性が向上する
- コメントは「なぜ」を書く
- 不要なコメントアウトは残さない
Kotlinでは、コメントは単なる補足ではなく、コード品質の一部です。
正しく使えば、読みやすさ・保守性・チーム開発効率を大きく高められます。
以上、Kotlinのコメントアウトについてでした。
最後までお読みいただき、ありがとうございました。
