Javadocの書き方を現役エンジニアが解説【初心者向け】

初心者向けにJavadocの書き方について解説しています。コード内にコメントを残すことで、各クラスやメソッドの役割などを参照することができるようになります。Javadocの記述方式を実際の例で確認しましょう。

TechAcademyマガジンはオンラインのプログラミングスクールTechAcademy [テックアカデミー]が運営。初心者向けに解説した記事が4,000以上あります。現役エンジニアの方はこちらをご覧ください。

Javadocの書き方について、TechAcademyのメンター(現役エンジニア)が実際のコードを使用して初心者向けに解説します。

 

Javaについてそもそもよく分からないという方は、Javaとは何なのか解説した記事を読むとさらに理解が深まるでしょう。

 

なお本記事は、TechAcademyのオンラインブートキャンプ、Java講座の内容をもとに作成しています。

 

田島悠介

今回は、Javaに関する内容だね!

大石ゆかり

どういう内容でしょうか?

田島悠介

Javadocの書き方について詳しく説明していくね!

大石ゆかり

お願いします!

 

Javadocとは

Javadocは、簡潔にいえばプログラムを説明するためのドキュメントを埋め込む仕組みのことです。

特定の書式に従って記述されたJavaプログラムのソースコードから、そのプログラムについて説明するドキュメント(リファレンス)を一定の規則に従って生成する仕組みとなっています。

例えば、クラスの概要やメソッドの概要をHTML形式のドキュメントファイルとして生成することができます。

このドキュメント形式はJavaクラスの仕様書の標準の書式です。

 

Javadocの書き方

Javadocの記述は、Javaプログラムのソースコード内にある「/**」と「*/」の間に記述します。

Javaプログラムのコメントは「/*」で始まり「*/」で終わります。そのため、Javadocとコメントを混同しないように気をつけましょう。

また、Javadocの中では「@」は特殊な記号として扱われます。

例えば、「@author」は開発者名、「@exception」はメソッドが投げる例がクラスとその説明「@param」はメソッドの引数名と引数の概要、「@return」はメソッドの戻り値といった具合です。

 

[PR] Javaで挫折しない学習方法を動画で公開中

実際に書いてみよう

下記のようなサンプルコードがあります。

public class Sample {
    public int area(int width, int height) {
        return width * height;
    }
}

このコードは、定義されているメソッドの役割は何なのか、メソッドを利用する際の引数は何なのか、さらに戻り値は何なのかがわかりにくい状態です。

しかし、サンプルコードに対してJavadocに対応したコメントを記述すると下記のように改善できます。

/**
 * 面積
 * @author Taro.Yamada
 */
public class Sample {
    /**
     * 四角形の面積を求める
     * @param width 幅
     * @param height 高さ
     * @return 面積
     */
    public int area(int width, int height) {
        return width * height;
    }
}

Javadocに対応した形でコメントを記述しておくだけで、定義したクラスやメソッドの内容がわかりやすくなります。加えて、即座にクラスやメソッドの仕様書を作成できるため非常に便利です。

しかし、実際の開発現場では、プロジェクト毎にJavadocの記述ルールが決まっています。そのため、個人の感覚で作成せずにルールに従ってJavadocコメントを作成しましょう。

 

執筆してくれたメンター

松井紀明

メーカー系で17年エンジニアとして勤務後、現在はフリーのエンジニアとしてリモートワークで働いています。

Java、Perl、COBOL、最近ではRuby、PHP等、様々な言語での開発を経験しています。

TechAcademyではJavaコースを担当しています。

 

大石ゆかり

Javadocの書き方がよくわかったので良かったです!

田島悠介

ゆかりちゃんも分からないことがあったら質問してね!

大石ゆかり

分かりました。ありがとうございます!

TechAcademyでは、初心者でも最短4週間でJavaやServletの技術を使ってWebアプリケーション開発を習得できるオンラインブートキャンプを開催しています。

また、現役エンジニアから学べる無料体験も実施しているので、参加してみましょう。