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

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

 

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

 

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

 

 

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コースを担当しています。

 

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

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