Java : 公式ドキュメントを読む癖をつけよう

公式ドキュメント、みなさんは活用していますでしょうか?
ウェブ検索は便利ですが、最終的な確認は公式ドキュメントで確認する癖をつけることをおすすめします。
この記事では公式ドキュメントのメリット・デメリットをご紹介します。

当サイトの「公式ドキュメントのリンク集」も参考にしていただけたら幸いです。


メリット

情報の鮮度、量、正確性は随一

これが一番大事です。
公式ドキュメント以外は、情報が古かったり不足していたり間違っていたりということもありえます。

幸いにもJavaの公式ドキュメントは日本語に翻訳されているものも多いので、ぜひ活用しましょう。

API仕様を読んでいれば、標準のAPIの命名規則にも自然と慣れていく

これは副次的なものですね。
自分でクラスを設計するときに、標準APIに合わせた命名にすれば、そのクラスを別のひとが使うときに「ああ、あの標準APIのあのクラスと似たように使えばいいのね」と理解してもらいやすくなります。

多人数で開発している場合は、意外と重要だったりします。

例:標準APIでは、不変なオブジェクト を取得するのに staticメソッドの of が多く使われています。

final var list = List.of(1, 2, 3);
final var localDateTime = LocalDateTime.of(2021, 3, 5, 20, 0);
final var path = Path.of("sample.txt");

自分でクラスを作るときも、of というメソッドを作れば、それは不変オブジェクトを取得するもの、と理解してもらいやすくなるでしょう。

関連記事:標準APIにならう命名規則

デメリット

必要な情報が探しにくい

つまり、答えを見つけるまでに時間がかかります。

公式ドキュメントをあまり見ない理由としては、これが多いのかなと思っています。
ウェブ検索はあいまいな検索ワードからピンポイントに答えの記事を見つけてくれます。非常に便利です。

ただ、経験上、公式以外のサイトだと自分の欲しい情報にはちょっと足りない、ということもよくあります。

ウェブ検索を使うことがNGというわけではありません。
調査の初動としては有効だと思います。うまく使いわけましょう。

備考

  • 最初は、公式ドキュメントを読むのは大変かなと思います。(文体もけっこう堅苦しい感じだし)
    ただ、次第に慣れてくると読む速度も上がっていきます。
  • 公式ドキュメントを読む時間はけっして無駄にはなりません。
    答えに直ぐにたどり着かなくても、読んだ情報は知識として蓄積されます。
    あきらめずに…

公式ドキュメントでは不足している情報もある

個人的に、API仕様にはもう少し使用例が欲しいですね。
API仕様だけ読んでもいまいち使いかたが分からず、実際にテストコードで試してみる、ということも…

まとめ

  • 公式ドキュメントを読もう。
  • ウェブ検索も有効に使おう。ただし最終確認は公式ドキュメントを読むことをおすすめ。

関連記事

ページの先頭へ