Kotlinのクラスドキュメントコメントの書き方ガイド｜初心者でもわかるKDocの基本と書き方

先生と生徒の会話形式で理解しよう

生徒

「Kotlinでクラスに説明を書く方法ってありますか？他の人が読んでも分かるようにしたくて…」

先生

「いい質問ですね。Kotlinでは、KDocという形式でコメントを書くと、他の人がクラスの意味を理解しやすくなりますよ。」

生徒

「KDocって何ですか？どうやって書くんですか？」

先生

「それでは、Kotlinでのドキュメントコメントの基本的な書き方を見ていきましょう！」

1. KDoc（ケイドック）とは？

KDoc（ケイドック）は、Kotlinで使われるドキュメントコメントの書き方のことです。プログラムの中に「説明文」を書いて、後から見たときに分かりやすくするための仕組みです。

KDocは、クラスや関数の上に/** ～ */で囲んで書きます。通常のコメント//や/* */とは違い、KDocコメントは自動的にドキュメント生成にも使われます。

2. クラスにKDocを書く基本的な書き方

KotlinのクラスにKDocを書くときは、次のような形式で書きます。


/**
 * ユーザーを表すクラスです。
 * ユーザー名と年齢の情報を保持します。
 */
class User(val name: String, val age: Int)

このようにクラスの上に説明文を書いておくと、他の人がこのクラスの目的や使い方をすぐに理解できます。

3. パラメータや戻り値を説明するタグ

関数などに対しては、KDoc内で@param（引数の説明）や@return（戻り値の説明）というタグを使うことができます。


/**
 * 年齢に応じた挨拶を返します。
 *
 * @param age ユーザーの年齢
 * @return 挨拶文
 */
fun greet(age: Int): String {
    return if (age < 18) "こんにちは、若者さん！" else "こんにちは、大人の方！"
}

こうすることで、関数が何をするものなのか、入力と出力が何なのかが明確になります。

4. プロパティ（変数）にも説明を書ける

クラスの中で使うプロパティにもKDoc形式で説明を書くことができます。特に大事な変数には説明をつけておくと親切です。


class Product(
    /**
     * 商品名（例：りんご、バナナ）
     */
    val name: String,

    /**
     * 価格（日本円）
     */
    val price: Int
)

コメントをつけることで、他の人がクラスの中身を読むときに迷いにくくなります。

5. KDocに書いてはいけないこと

KDocは説明を書く場所ですが、「コードと重複すること」や「曖昧な表現」は避けましょう。

悪い例： この関数は値を返します。（→ 何の値か分からない）
良い例： 商品の価格（税込）を計算して返します。

具体的で簡潔な言葉を使いましょう。

6. IDEでの自動補完も活用しよう

IntelliJ IDEAやAndroid Studioなどの開発ツール（IDE）では、KDocを書くと自動補完が効くことがあります。/**と書いてEnterを押すと、テンプレートが出てくることもあります。

この機能を使えば、手間をかけずにコメントが書けるのでおすすめです。

7. KDocで使えるその他のタグ

KDocでは、@constructor や @sample といったタグも使えますが、初心者のうちはよく使う @param と @return だけで十分です。

必要になったときに、他のタグも覚えていけば大丈夫です。

8. 実践！KDocを使ったクラスの記述例

実際に、クラス全体にKDocを使ってコメントを書いた例を見てみましょう。


/**
 * 書籍を表すデータクラスです。
 *
 * @property title 本のタイトル
 * @property author 著者名
 */
data class Book(val title: String, val author: String)

/**
 * 図書館を管理するクラスです。
 * 本を追加したり一覧表示できます。
 */
class Library {
    private val books = mutableListOf<Book>()

    /**
     * 新しい本を追加します。
     *
     * @param book 追加する書籍
     */
    fun addBook(book: Book) {
        books.add(book)
    }

    /**
     * 登録されている本の一覧を取得します。
     *
     * @return 書籍のリスト
     */
    fun listBooks(): List<Book> = books
}


[Book(title=Kotlin入門, author=田中 一郎)]

このようにコメントが丁寧に書かれていると、初めて読む人にも分かりやすくなります。

まとめ

Kotlinでプログラムを書くとき、見た目だけでなく「どう書かれているか」が非常に重要になります。とくに初心者のうちは、他人が書いたコードを読んだり、自分が書いたコードを時間が経ってから見直したりするときに「これ何のためのクラスだっけ？」と迷うことがよくあります。そんなときに役立つのが、KDoc（ケイドック）によるドキュメントコメントです。

このKDocを使えば、クラスや関数、プロパティに「どんな目的で作られたのか」「どう使うのか」などを明記できるため、自分以外の人や未来の自分に対して非常に親切な設計となります。

特に大切なのは、クラスの役割を明確に書くことと、@paramや@returnといったタグを使って、入力と出力が何であるかを分かりやすく示すことです。さらに、プロパティ単位でもKDocが使えるため、細かな情報まで丁寧に伝えることができます。

KDocコメントを書くには、/** ～ */ の形式を使います。通常のコメント（// や /* */）と異なり、KDocは将来的にドキュメント化ツールで自動的に表示されるため、わかりやすい説明文を書くことが求められます。

たとえば次のようなクラスがあったとします。


/**
 * 商品情報を管理するクラスです。
 *
 * @property name 商品名
 * @property price 商品の価格（円）
 */
data class Item(val name: String, val price: Int)

/**
 * 商品リストを扱うユーティリティ関数です。
 *
 * @param items 商品の一覧
 * @return 合計金額
 */
fun calculateTotal(items: List<Item>): Int {
    return items.sumOf { it.price }
}

このようにコメントをつけておくだけで、他の開発者がクラスや関数を読むときに、ぱっと見ただけで全体像をつかめます。「Kotlinでクラスに説明を書く方法」や「KDocの書き方」が分かれば、チームでの開発やコードレビューもスムーズになりますし、自分自身も成長を実感しやすくなります。

また、IDE（IntelliJ IDEAやAndroid Studio）では、/**と書いてEnterキーを押すだけで自動的にKDocの雛形が出てくる補完機能もあります。この機能を使うことで、書き漏れを防ぎつつ効率よく説明を書くことができるのです。

最後に覚えておきたいのは、「KDocは読む人のための思いやり」ということ。コードの動きだけでなく、その意図や背景まで丁寧に記述していくことで、読みやすく、使いやすく、そして信頼されるコードになります。初心者のうちからこの習慣を身につけておくと、今後どんな言語を学んでも役立つ「伝わるコード」が書けるようになるはずです。

先生と生徒の振り返り会話

生徒

「先生、KDocって最初はちょっと面倒だと思ってましたけど、クラスや関数の意味をハッキリ書けるから便利ですね！」

先生

「そうなんです。Kotlinのクラスや関数にKDocをきちんと書くと、将来の自分や他の人がコードを読むときの助けになります。特にチーム開発では必須とも言えますね。」

生徒

「@paramや@returnの使い方も分かってきました！あと、自動補完でコメントの型が出てくるのも地味に助かります。」

先生

「その調子です。コードを書くことと同じくらい、分かりやすく説明することも大切なスキルですから、今のうちからKDocに慣れておきましょう。」

生徒

「はい！これからクラスや関数には、ちゃんとKDocで説明を書くようにします！」