Java
初心者
規約
javadoc

【一年生の頃の私へつづる言葉⑪】最低限のJavaコーディング作法を把握してね。(二通目 : Javadoc編)


  • 今となっては、当然のごとく使用していることを、ただ手紙としてしたためるだけの記事の第十一弾。

  • 毎日の更新を、二日ほど空けるはめになって、何ものにも代えられる気持ちで、時間跳躍ごっこをしていく。

  • 二日しか経っていなくても、久々という感覚になるということに、いかに毎日現実からの逃避を続けて、幻想と真摯に向き合ってきたかが分かる。

  • 今回は、前回の続きで、Javaコーディング作法の二通目を送ることにしよう。


Javaコーディング作法


<当時>


  • 「規約」・・・クラスやメソッドや変数等の、基礎的な命名のみ、気を付けていた。


  • 「作法」・・・学習段階から、意識して記述しておらず、意味さえ通じれば良いと思ってた。

→チーム開発等において、統一性や可読性に欠ける記述をしてしまい、多大なご迷惑をかける。


<現在>


  • 書籍やネット等で、規約や作法に関して基礎から学習しなおす。

  • サンプルプログラムやオープンソースプロジェクト等を見ながら、人のコードを確認する。


Javadoc


概要


  • Javadocとは、ソースコードからHTML形式のAPI仕様書を生成する仕組みのこと。

  • 形式によって記述しておくことで、定義したメソッドやクラスの説明のドキュメントをJavadocで簡単に作成することができる。


ルール


  • 「/**」と「*/」の中にコメントを書く。

  • 本文は、基本的にHTML形式で記述。

  • 区分として、「説明文」「タグセクション」に分けられる。


    • 「説明文」は、HTML文として認識。複数行に分けるときは、 <pre>等の改行タグを使用。

    • 「タグセクション」は、@で始まる。


      • 複数回使用できるものと、1回のみ使用可能なタグがある。

      • タグセクション記述の後に、説明文記述はダメ。



    • 種類として、主に下記がある。



      • @author


        • 記述者(作者)を表す。

        • 複数回指定可能。




      • @version


        • 現在のソフトのバージョンを表す。

        • 複数回指定可能。




      • @see


        • 関連項目。記述内容として主に下記。


          • テキスト。

          • リンク。<a>タグが指定可能。

          • 参照リンク


            • 「パッケージ名.クラス名#メソッド名」の形式で記述。





        • 複数回指定可能。




      • @deprecated


        • 非推奨のクラスやメソッドの明記に用いる。

        • 複数指定不可能




      • @since


        • 導入されたソフトのバージョンを表す。

        • 複数回指定可能。




      • @param


        • パラメータ(引数)名、その説明に用いる。


          • 名前と意味の間に改行を入れる。

          • 意味の行を、インデント(字下げ)して記述。



        • 複数回指定可能




      • @return


        • 戻り値に関する(型や範囲)説明に用いる。

        • 複数回指定不可能。




      • @throws(@exception)


        • 例外の可能性がある部分において、「例外型」と「発生起因」の説明に用いる。




      • {@link}


        • 文字列表示箇所の参照リンクの明記に用いる。

        • インラインタグと呼ばれる。

        • 記述は、「{@link パッケージ名.クラス名#メソッド名}」の形式で記述。




      • {@linkplain}


        • 文字列表示箇所の参照リンクの明記に用いる。


        • {@link}タグとの違いは、文字列が プレーンテキストであるということ。

        • 記述は、「{@linkplain パッケージ名.クラス名#メソッド名}」の形式で記述。








  • ドキュメントの種類として、主に下記がある。


    • クラスドキュメント


      • 最初に役割や機能を簡潔に書く。

      • 詳細に説明する場合、次の段落に書く。

      • 最後に必要に応じて、Javadocタグの「@author」「@version」「@see



    • インターフェースドキュメント


      • 最初に役割や機能を簡潔に書く。

      • 詳細に説明する場合、次の段落に書く。

      • 最後に必要に応じて、Javadocタグの「@author」「@version」「@see」を書く。



    • フィールドドキュメント


      • フィールドの名称のみを書く。



    • メソッドドキュメント


      • 最初に役割や機能を簡潔に書く。

      • 詳細に説明する場合、次の段落に書く。

      • 最後に必要に応じて、Javadocタグの「@param」「@return」「@throws」「@Exception」を書く。






/**

* テストクラス
*
* @author t_o_d
* @version 4.6
* @see <a href="https://www.google.co.jp/">Google</a>
*/

public class Test{
/**
* メッセージ
*/

private String message;

/**
* 年齢
*/

private int age;

/**
* 情報の設定

* @param name
名前
* @param number
個人番号
@deprecated 別メソッドからの置き換え {@link #infoConfiguration(String name, int number)}
*/
public void setInfo(String name, int number){

}

/**
* メッセージの取得
* @return メッセージ
*
* <pre>
* 設定は{@link com.example.Main#setResult()}
* 設定は{@linkplain com.example.Main#setResult()}
* </pre>
*
* @since 4.6
*/

private int resultCalculation(int firstNumber, int secondNumber) {
return number1 + number2;
}

/**
* 読み込み
* @throws java.io.IOException
* 入出力に関するエラー
*/

public void readFromFile() throws IOException{

}
}


まとめ


  • 今回は、コーディング作法の二通目ということで、「指定形式での自動ドキュメント作成」に一目惚れの感覚に近い感情を抱いていた頃を思い出しながら、記事を書く。

  • 「全てにおいて、最低限の頼みで何でもしてくれるようになったら嬉しい」と、刑罰を設けてでも「交際」をさせるべきではない方がいい典型的な私は、もはやどうしようもない。

  • 「そういう理由で制限人生を送っている私は、運命をきちんと受け入れて、これからも幻想遊びと無駄調査等に専念することを誓います」という、誰の記憶にも残らない宣誓を誇らしげに行う。


参考