1. KDocとは？Kotlinの関数に説明を加える方法

KotlinのKDoc（ケードック）は、関数・クラス・プロパティに「何をするコードなのか」を明確に伝えるためのドキュメンテーションコメントです。対象の直前に/** ... */で記述すると、IntelliJ IDEAやAndroid Studioがツールチップやクイックドキュメントで表示してくれます。通常の//や/* */と違い、KDocは開発ツールが理解できる正式な説明書きとして扱われるのが特徴です。

まずは最小限の使い方を見てみましょう。概要を1～2文で書くだけでも、後から読む人（未来の自分を含む）が理解しやすくなります。KDocは必ず説明したい宣言（関数やクラス）の直前に置くのが基本ルールです。


/**
 * 「こんにちは」を返すシンプルな関数。
 * 何をするのかを短く書くだけでも効果があります。
 */
fun hello(): String {
    return "こんにちは"
}

このようにKDocを添えておくと、コードを参照した瞬間に意図が伝わります。まずは「概要を1文で書く」ことから始めるだけで、読みやすさと保守性がぐっと向上します。

2. KDocコメントの基本的な書き方

関数の説明を書くには、関数の前に/** */を使って書きます。次のように記述します。


/**
 * 与えられた名前を使ってあいさつを表示する関数です。
 *
 * @param name あいさつする相手の名前
 * @return あいさつの文字列
 */
fun greet(name: String): String {
    return "こんにちは、$name さん！"
}

このように@paramで引数、@returnで戻り値の説明を書くのが一般的です。

3. なぜKDocを書くの？初心者にもわかる理由

KDocは、自分や他の人がその関数を見たときに、すぐに「何をするのか」「どう使うのか」がわかるようにするための説明文です。特にチーム開発や時間がたったあとに見直すときにとても役立ちます。

また、Kotlinに対応した開発ツール（たとえば IntelliJ IDEA や Android Studio）は、KDocコメントをマウスオーバーやヒント表示に使ってくれるため、読みやすくなります。

4. よく使うKDocのタグ一覧

@param：関数の引数を説明します。
@return：戻り値がある場合に、その内容を説明します。
@throws（または@exception）：例外が発生する場合に、その内容を説明します。
@constructor：クラスのコンストラクタの説明に使います。
@property：プロパティ（変数）の説明に使います。

5. 実例で学ぶKDocコメントの応用

次は、少しだけ複雑な関数にKDocを付けた例です。


/**
 * 年齢をもとに、飲酒できるかどうかを判定する関数です。
 *
 * @param age ユーザーの年齢
 * @return 飲酒可能ならtrue、そうでなければfalse
 */
fun canDrinkAlcohol(age: Int): Boolean {
    return age >= 20
}

このように、関数の内容を簡潔に説明し、引数や戻り値の意味をはっきりと書くことが重要です。

6. 開発ツールでKDocを確認する方法

Kotlin対応の開発環境（たとえば IntelliJ IDEA）では、関数にマウスを合わせるだけでKDocコメントがポップアップ表示されます。これは関数の使い方をすぐに確認できる便利な機能です。

また、Ctrlキーを押しながら関数にマウスを合わせると、ドキュメントとしての詳細表示も確認できます。

7. コメントを使うときの注意点とコツ

難しい言葉は使わず、できるだけ簡単な日本語で説明しましょう。
関数の目的がはっきり伝わるように、一文でもいいので意味のある説明をつけましょう。
他の人が読んで「なるほど！」と思えるような書き方を意識するのがポイントです。

KDocは「誰かのためのメモ」です。未来の自分や、チームメンバーのために書く意識を持つと、より良いコードになります。

まとめ

Kotlinの関数に説明を加えるためのドキュメンテーションコメント、すなわちKDocについて、今回は基本から応用まで丁寧に解説しました。プログラムを書くうえで、関数の意味や引数の目的、戻り値の内容などを他人にも自分にもわかりやすくするためには、コメントの役割が欠かせません。その中でもKDocは、特別なフォーマットで書くことで、開発ツールと連携して視認性を高めたり、ドキュメントとして自動生成にも対応できたりと、多くのメリットをもたらしてくれます。

特に初心者にとっては、Kotlinの関数やクラスが増えてくると、コードの内容をあとから思い出すのが難しくなりがちです。そんなとき、KDocで説明が書いてあれば、再確認がしやすく、修正や拡張の際にも大いに役立ちます。たとえば、関数の上に以下のように記述するだけで、意味を明確にできます。


/**
 * 数値が偶数かどうかを判定します。
 *
 * @param number 判定対象の整数
 * @return 偶数ならtrue、奇数ならfalse
 */
fun isEven(number: Int): Boolean {
    return number % 2 == 0
}

このような書き方は、読み手にとって優しさを伝えるだけでなく、開発全体の品質向上にもつながります。KDocにはよく使われるタグとして、@param（パラメータの説明）、@return（戻り値の説明）、@throws（例外説明）などがあり、目的に応じて使い分けることが大切です。

また、ツールとの相性も抜群で、IntelliJ IDEAやAndroid Studioでは、KDocが自動的にポップアップ表示され、関数を理解するための助けとなってくれます。これはまさに、チーム開発や保守作業での強い味方となるでしょう。

コメントを書くという作業は、ともすれば後回しにされがちですが、実はコードと同じくらい大切です。未来の自分を助けるため、そして他の開発者が理解しやすいコードにするために、KDocの活用はぜひ習慣にしておきたいところです。

最後に、ドキュメントを書く際には、難しい表現を避け、誰でも理解できる簡潔な言葉を選ぶのがコツです。説明の対象はエンジニアだけでなく、将来の初心者かもしれないという気持ちを持つと、自然と伝わりやすいコメントが書けるようになります。

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

生徒

「KDocってただのコメントかと思ってたけど、開発ツールと連携してくれるんですね！」

先生

「そうなんです。マウスオーバーで説明が表示されたり、チーム開発でも大活躍ですよ。」

生徒

「しかも@パラメータとか@リターンとか、ルールが決まってるから分かりやすいですね。」

先生