【一年生の頃の私へつづる言葉⑪】最低限の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`」を書く。

### 例

```java
/**
 * テストクラス
 *
 * @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/   
→こちらの記事を参考にしました。大変お世話になりました。