今となっては、当然のごとく使用していることを、ただ手紙としてしたためるだけの記事の第十一弾。
毎日の更新を、二日ほど空けるはめになって、何ものにも代えられる気持ちで、時間跳躍ごっこをしていく。
二日しか経っていなくても、久々という感覚になるということに、いかに毎日現実からの逃避を続けて、幻想と真摯に向き合ってきたかが分かる。
今回は、前回の続きで、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{

  }
}

まとめ

今回は、コーディング作法の二通目ということで、「指定形式での自動ドキュメント作成」に一目惚れの感覚に近い感情を抱いていた頃を思い出しながら、記事を書く。
「全てにおいて、最低限の頼みで何でもしてくれるようになったら嬉しい」と、刑罰を設けてでも「交際」をさせるべきではない方がいい典型的な私は、もはやどうしようもない。
「そういう理由で制限人生を送っている私は、運命をきちんと受け入れて、これからも幻想遊びと無駄調査等に専念することを誓います」という、誰の記憶にも残らない宣誓を誇らしげに行う。

参考

https://www.javadrive.jp/javadoc/
→こちらの記事を参考にしました。大変お世話になりました。