上司にアドバイスをいただいた
Javaのソースコードを実装する際に
やった方がいい事
こうした方が効率が良くなるよ
とかを記録、メモ
(随時更新)
Javadocは、メソッドとかクラスを作った(書いた)時点で書いてしまった方がいい
経緯:
時間があまり無い状況で、「まずは動くものを作ることを優先しよう!!」と考え、Javadocの記載を後回しにしていた。
しかし、上司から「後から書くと、二度手間になるし、記載漏れも出てくるでしょ。後回しにする理由も無いし、すぐに対応してしまった方がいいよ。」とご指摘をいただいた。
(上司の場合、Javadocは、メソッドとかクラスを作った(書いた)時点で書いてしまっているとのこと)
--
- 実装し終わったクラスやメソッドにまた戻ってこなくてはいけない
- 『これってなんのクラス、メソッドだっけ?引数、戻り値はなんだっけ??』と、思い出す(考える)必要がある
- 1.で戻る際に、記載漏れが発生するかも
→1、2の時点で二度手間
3で記載漏れ(修正の場合は修正漏れ)が発生する
--
Javadoc
公式サイト
Javadocの主な記述箇所
記述箇所 | 説明 | 例 |
---|---|---|
クラス | クラスの役割を記述 (バージョンや、作成者の情報もここに記述) |
/** ほげほげControllerクラス. */ public class HogehogeController{ |
コンストラクタ | コンストラクタの説明を記述 | public class HogehogeController{ /** * デフォルトコンストラクタ. */ HogehogeController(){ this.hugahuga = 0; } |
フィールド | フィールドがどんな意味のデータを保持するのかを記述 | /** 学生情報Dao. */ private StudentDao studentDao; |
メソッド | メソッドの ・説明 ・引数 ・戻り値 ・発生する例外 などの説明を記述 |
/** 学生情報を更新する. */ public void updateStudent(int id, String studentName) throws SQLException { |
公式サイト
より
説明
javadocコマンドは、一連のJavaソース・ファイルにある宣言およびドキュメンテーション・コメントを解析し、デフォルトではpublicクラス、protectedクラス、ネストされたクラス(匿名の内部クラスは除く)、インタフェース、コンストラクタ、メソッド、およびフィールドについて説明した一連のHTMLページを生成します。javadocコマンドを使用すると、APIドキュメントや、一連のソース・ファイルの実装ドキュメントを生成できます。
Javadocで使用できるタグ
タグ | 説明 | 公式サイトより | 備考 |
---|---|---|---|
@param 変数名 説明 |
メソッドの引数、ジェネリクスの型の説明を記述 | > @param parameter-name description |
- |
@return 説明 |
メソッドの戻り値の説明を記述 | > @return description |
- |
@throws 例外クラス 説明 |
メソッドでスローされる例外の説明を記述 | > @throws class-name description |
公式のHow to Write Doc Comments for the Javadoc Toolより > Document the following exceptions with the @throws tag:> All checked exceptions. > (These must be declared in the throws clause.) > Those unchecked exceptions that the caller might reasonably want to catch. > (It is considered poor programming practice to include unchecked exceptions in the throws clause.) > Documenting these in the @throws tag is up to the judgment of the API designer, as described below.1
|
- Javadocの記載は、
<br>
で改行できる
ログの書き方
参考サイト
HTTPステータスコード
Java8
HttpURLConnection
実装
関数の「戻り値」以外で、関数の呼び出し元に値を返す方法
try-catchで捕まえて throwする
別なファイルとかに出力して、出力したものを別なヤツで読み込む
-
Javadocの
@throws
タグを記載しなくてはいけない時はどんな時なのかについては、Javadocの@throwsタグを記載しなくてはいけない時を参照 ↩