読者です 読者をやめる 読者になる 読者になる

日々常々

ふつうのプログラマがあたりまえにしたいこと。

WEB+DB PRESS vol.93のJavaの新定石は"マルチスレッド/GCとの付き合い方"です。

2016-06-24に発売してました。1ヶ月経ってるので、だいたい読んでくれてると信じてます。まだの方は是非。

WEB+DB PRESS Vol.93

WEB+DB PRESS Vol.93

前回も書いた通り、この連載は「昔からJava使ってるけど、最近の変化とかいちいち追うのめんどい」って方が対象です。今回のマルチスレッド関連はThreadから通して駆け抜けてみたり。書きながら書いたコードは私のGitHubの砂場に転がってたりします。

マルチスレッドとGCについては、Javaエンジニア養成読本の第5章ですこし触れてます。あちらは40ページ中の合わせて1ページでしたが、今回は8ページ中の8ページ。だからどうした。

Javaエンジニア養成読本からは1年半経ってますが、この程度の期間でそれほどJavaのこの辺は変わってませんし、多少増えた私の知識もたいして影響ない程度です。と言うことで、ある意味では書いてる内容やオチに差はないです。見比べたらわかるかも。

Javaエンジニア養成読本 [現場で役立つ最新知識、満載!] (Software Design plus)

Javaエンジニア養成読本 [現場で役立つ最新知識、満載!] (Software Design plus)

ちなみに「Javaの新定石」はうらがみさんと一緒に書かせて貰ってます。何気に一番勉強になってるのは私ではなかろうかね、と思ったり。

WEB+DB PRESS vol.92から「Javaの新定石」って連載、はじめました。

連載はじまります。よろしくおねがいします。

WEB+DB PRESS Vol.92

イメージは高速道路。知識の高速道路とか言うアレです。 ワープや発生ではないです。いきなり新しいものが出てくるのではなく、昔から繋げつつ駆け抜ける感じ……になるのかな。 そんな風なことを書いていきたいなーと思ってます。

メインターゲットは「昔からJava使ってるけど、最近の変化とかいちいち追うのめんどい」って方です。 それだけじゃなく、Javaやってる人に広く合うんじゃないかなー。

定石

あまり関係ないですけど、定石*1って知ってても勝てないんです。 定石を知ってる同士で組み合って、そこからお互い思考を重ねたりして、最後には唯一無二の棋譜ができる。そんな感じ。

定石には理由があるけれど、理由は知らずに手順を暗記しているだけでもそれなりに様になります。 とういうのも、定石は最善手から成立していて、定石の範囲内では基本的に互角になります。

つまり、定石から外れるとは、あえて不利な手を指すことになります。 この際、定石を守ってる側が定石の理由を知らなかったら、一気に崩れることもままあります。 理解していたら、相手の悪手に乗っかって有利に進められることが多いのですけど。

とか何とか言いつつ、もう何年も将棋指してないや。

あ、連載タイトルとはたぶん関係ありません。

*1:私は将棋指しだったので定跡と書く方が多いのだけど

Kotlinに手を出してみる

Kotlinをはじめてみよう。

と思って、こんなことをした。

  • インストールする
  • はろわをかく
  • javapして眺める
  • Kotlinに依存しない形(javaコマンド)でkotlincでコンパイルしたクラスを動かす

GitHubのほうに同じのをあげてるます。

インストールしてみる

sdkmanでいけるんじゃないかと思って、sdk install kotlinを叩いてみる。

% sdk install kotlin

Downloading: kotlin 1.0.1

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
100   601    0   601    0     0    359      0 --:--:--  0:00:01 --:--:--   558
100 19.6M  100 19.6M    0     0   984k      0  0:00:20  0:00:20 --:--:-- 1586k

Installing: kotlin 1.0.1
Done installing!

Do you want kotlin 1.0.1 to be set as default? (Y/n): y

Setting kotlin 1.0.1 as default.

入ったわ。

げってぃんぐすたーてっどを探す

文法もわからんからとりあえずググる

一番上に公式が出てきてくれた時の安心感。

開いたら当然のように「IDEAでやろうぜ!」って言われる。 まあわかるけど、私はとりあえずコマンドラインvimでやりたいんだーと思ったら、それっぽいのがある。

……ん。sdkmanで入れろって書いてる。 いいや。とりあえずはろーわーるど書いてみよう。

はろわ!

書くぜー。

ふむ。 そしてこんぱいr……ん?

$ kotlinc hello.kt -include-runtime -d hello.jar

なんかコマンド長いなーと思った。 まあいいか。実行したらhello.jar ができた。

サイズは80kbくらい、そこそこでかい。 -include-runtimeとかついてるし、実行可能jarなんだろと思って実行。

% java -jar hello.jar
Hello, World!

できたできた。

zip展開してjavap

どうせ hello.class とかあるんだろうと思ってunzipしたら、なんか HelloKt.class ってのが入ってた。

% javap HelloKt
Compiled from "hello.kt"
public final class HelloKt {
    public static final void main(java.lang.String[]);
}

こいつそのまま実行したらいけるんだろうなーと。

% java HelloKt
Hello, World!

いけた。 んー、これだけならクラスだけでも動くのかな。 って思って、クラスだけ移動して実行。

% java HelloKt
Exception in thread "main" java.lang.NoClassDefFoundError: kotlin/jvm/internal/Intrinsics
  at HelloKt.main(hello.kt)
  Caused by: java.lang.ClassNotFoundException: kotlin.jvm.internal.Intrinsics
    at java.net.URLClassLoader.findClass(URLClassLoader.java:381)
    at java.lang.ClassLoader.loadClass(ClassLoader.java:424)
    at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:331)
    at java.lang.ClassLoader.loadClass(ClassLoader.java:357)
    ... 1 more

だめか(当たり前だ

mainメソッドの中でクラスロードが入ってる。 なんだろう。

$ javap -v HelloKt
...略
  #15 = Methodref          #11.#14        // kotlin/jvm/internal/Intrinsics.checkParameterIsNotNull:(Ljava/lang/Object;Ljava/lang/String;)V
...略
public static final void main(java.lang.String[]);
    descriptor: ([Ljava/lang/String;)V
    flags: ACC_PUBLIC, ACC_STATIC, ACC_FINAL
    Code:
      stack=2, locals=3, args_size=1
         0: aload_0
         1: ldc           #9                  // String args
         3: invokestatic  #15                 // Method kotlin/jvm/internal/Intrinsics.checkParameterIsNotNull:(Ljava/lang/Object;Ljava/lang/String;)V
         6: ldc           #17                 // String Hello, World!
         8: astore_1
         9: nop
        10: getstatic     #23                 // Field java/lang/System.out:Ljava/io/PrintStream;
        13: aload_1
        14: invokevirtual #29                 // Method java/io/PrintStream.println:(Ljava/lang/Object;)V
        17: return
...略

パラメーターのnullチェックをメソッドの先頭でやってるんだなーと。

javap見た感じ、そいつあったら動く気がする。 適当に作ってみる。

そして実行。

% java HelloKt
[Ljava.lang.String;@7852e922
args
Hello, World!

動いた。謎の自己満足。

そんなわけで

Kotlin勉強会の裏で書いてました。

この後は素直にIDEAで触ることにします。

EC2のAmazonLinuxにPayaraを放流してみた

Java AWS

前置き

EC2さん。便利ですよね。使ってますか?私はあまり使ってないです。別にほかのサービス使ってるとかでもないです。(ドヤ顔で目線を逸らしながら

たまに思い出したように触っては、ある程度使えるつもりになって。 しばらくしたら使い方を綺麗さっぱり忘れて、AWS Consoleにログインするたびにいろいろ変わってて戸惑うってのを繰り返しています。 いい加減にしたい。いや、これがいい加減なのか。

ふとしたことから雑なJavaEEアプリケーションを突っ込んだPayara microをEC2で動かしたいなーと思って、また思い出したようにEC2を触るわけで、また一からあれこれやってました。

理想と現実

理想

  • EC2インスタンスを立ち上げて
  • Payaraダウンロードしてきて
  • war放り込んで
  • 起動したら完了

現実

  • EC2立ち上げるかー。microでいいか……ん、そいやnanoとかあったね。知ってる知ってる。聞いた事はある。
  • jdkのインストールとか要ったね。あったあった。
  • payaraさんダウンロード、短縮URLだけど……まあいけるか。
  • コマンドわからん。wgetわからん。yumもわからん。 ← いつものこと
  • さあ起動だ!……ん?……例外? ← new

Payaraさんを放り込んだら例外吐いて死んだ

jdkのインストール

まずはいつものアレ。

$ sudo yum install java-1.8.0-openjdk-devel
$ sudo alternatives --config java
(なんか出てくるので1.8.0を選択)

1.8.0_65だった。まあいいか。

参考: Amazon LinuxでJava8/Tomcat8の環境を構築する

payaraのインストール

次に http://www.payara.fish/downloads からリンクをコピーしてきてwgetする。

$ wget http://bit.ly/1W9d2Lb

ファイル名が 1W9d2Lb になるけど気にしない。 適当にmvした。

payaraの起動

まだwarとか放り込んでないのでそのまま起動する。

$ java -jar payara-micro-4.1.1.154.jar

……ふつうはこれでいいのだけれど、こんなエラーになっちゃって。

$ java -jar payara-micro-4.1.1.154.jar
1 24, 2016 10:33:44 午前 com.sun.enterprise.v3.server.SystemTasksImpl setSystemPropertiesFromEnv
重大: Cannot determine host name, will use localhost exclusively
java.net.UnknownHostException: ip-XXX-XXX-XXX-XXX: ip-XXX-XXX-XXX-XXX: unknown error
    at java.net.InetAddress.getLocalHost(InetAddress.java:1505)
(中略)
    at fish.payara.micro.PayaraMicro.main(PayaraMicro.java:105)
  Caused by: java.net.UnknownHostException: ip-XXX-XXX-XXX-XXX: unknown error
    at java.net.Inet4AddressImpl.lookupAllHostAddr(Native Method)
(中略)
    at java.net.InetAddress.getLocalHost(InetAddress.java:1500)
    ... 29 more

(中略)

[2016-01-24T10:33:55.956+0000] [Payara 4.1] [INFO] [NCLS-JMX-00006] [javax.enterprise.system.jmx] [tid: _ThreadID=87 _ThreadName=Thread-12] [timeMillis: 1453631635956] [levelValue: 800] JMXStartupService has disabled JMXConnector system

Exception in thread "main" java.lang.NullPointerException
  at fish.payara.micro.services.PayaraMicroInstance.setInstanceName(PayaraMicroInstance.java:95)
    at fish.payara.micro.PayaraMicroRuntime.<init>(PayaraMicroRuntime.java:64)
    at fish.payara.micro.PayaraMicro.bootStrap(PayaraMicro.java:710)
    at fish.payara.micro.PayaraMicro.main(PayaraMicro.java:105)

とても悲しい。 起動はしてるのでサーバーのエラーページを表示することはできるのだけれど、--deployでwarを放り込んでも動いてくれない状態だった。

ホスト名が見つからないって言ってて、出てるのはローカルのホスト名。なので /etc/hostslocalhostに足してあげる。

$ hostname
ip-XXX-XXX-XXX-XXX
$ sudo vi /etc/hosts
127.0.0.1   localhost localhost.localdomain ip-XXX-XXX-XXX-XXX

参考: EC2 インスタンス上に Cassandra クラスタを構成する〜 java.net.MalformedURLException の対処 〜

よくわからんけど 動くようになったからよし。

放流

  • scpとかでwarを放り込んで
  • java -jar payara-micro-4.1.1.154.jar --deploy hoge.war で起動

これで完了。やったね。

コンストラクタのメソッド利用で注意すること

Java Java入門+α

Java入門ではさらっと以下のように書いた、コンストラクタインスタンスメソッドを実行することについて掘り下げてみます。

コンストラクタからインスタンスメソッドを使用することは可能ですが、避けたほうが無難です。 コンストラクタの実行中はインスタンス自体が構築中のため、初期化が完了していない状態でメソッドが実行されることになります。

Javaエンジニア養成読本 [現場で役立つ最新知識、満載!] (Software Design plus)

Javaエンジニア養成読本 [現場で役立つ最新知識、満載!] (Software Design plus)

文章だけで伝えるのはなかなか難しいものだとも思いますし、 本に書いたのに実際にこの問題を見た時に即解決できなくて悔しかった ので、 突っ込んでしっかり書くことにしました。くそう。。。

簡単なサンプルコード

コンストラクタでのインスタンスメソッド呼び出しが問題を起こすコードは、以下のようになります。

/* このコードは動作しません */
class Hoge {
    final String str;

    Hoge () {
        invoke();
        this.str = "HOGERA";
    }

    void invoke() {
        System.out.println(str.length());
    }
}

new Hoge()とかするとNullPointerExceptionです。

Exception in thread "main" java.lang.NullPointerException
  at blog.constructor.Hoge.invoke
  at blog.constructor.Hoge.<init>

このくらい短いコードなら、流石にやらないでしょうが、 コンストラクタinvokeメソッドの間に数百行の隔たりがあればどうでしょう? フィールドはfinalだし、うっかり使ってしまうかもしれません。 作成時は問題がなかったとしても、不具合改修などでこの手の問題が起こしてしまったとしても、 その開発者を不注意だと責め立てることは、私には出来そうもありません。(自分もやっちゃうだろうし。)

少し複雑にしたサンプルコード

さらに問題を複雑にすると、冒頭のように1クラスに完結している形では問題なく動作しているにもかかわらず、 継承すると問題が起こるパターンも考えられます。擬似的なコードは次のようなものになります。

/* このコードは動作しません */
abstract class Parent {

    final String arg;

    Parent(String arg) {
        init();
        this.arg = arg;
    }

    abstract void init();
}

class Child extends Parent {

    Child(String arg) {
        super(arg);
    }

    @Override
    void init() {
        System.out.println(arg.toUpperCase(Locale.ROOT));
    }
}

new Child("xxx")とかでNullPointerExceptionになります。

Exception in thread "main" java.lang.NullPointerException
  at blog.constructor.Child.init
  at blog.constructor.Parent.<init>
  at blog.constructor.Child.<init>

少し説明落ち着いてコードを追えば、コンストラクタ引数がフィールドに格納される前に、 そのフィールドを参照しているので、フィールド型のデフォルト値(参照型なのでnullになる)となっているだけです。

しかし、このNullPointerExceptionに遭遇すると、おそらく「finalフィールドなのになぜ値が入っていないんだ?」となります。 コンストラクタの引数がnullになっていないかや、どこかで受け渡し損ねてないかなどを確認するかもしれません。 デバッガでinitメソッドにブレイクポイントを置いてみたりするかもしれません。いくら見ても、事実が示すようにフィールドはnullです。

継承階層が深くなると、メソッドの呼び出しタイミングがわからなくなっていきます。 全てのコードの詳細を把握することは困難ですし、全ての人にそれを求めるべきではありません。 上記のようにinitメソッドが拡張ポイントのように扱われていると、フレームワークコンストラクタの後に呼びだす初期化処理と想像しても、不思議ではないでしょう。

さらに複雑にした(略

もっと複雑に、もっとわかりにくくすることは可能です。もっともっと。 でも、書いても楽しくないので箇条書きで許してください。

  • コンストラクタで呼ばれるメソッド(上記だとinit)で例外が発生せず、そこから呼び出したメソッドで発生する。
  • コンストラクタで呼ばれるメソッドで生成されたインスタンスにフィールドのデフォルト値が設定される。
    • nullで即例外が発生すればいいのですが、生成されたインスタンスに意図せぬ値が入ったまましばらく経ち、別のタイミングで不正な状態で実行されることになります。
    • このパターンでさらに問題を起こすクラスのインスタンス生成箇所が多かったりすると、原因の特定難度はさらに上がります。
  • 対象がプリミティブ型
    • 参照型であればNullPointerExceptionが発生することで助かります(そう、例外が発生すればまだ助かるのです。少なくとも不正な更新を行ったりしてデータを壊す可能性は下がります。ぬるぽはいい子です。)が、プリミティブ型ならおそらくデフォルト値でそのまますんなり動いてしまいます。
  • フィールド参照ではなく、そのフィールドを使用する別のメソッドを使用する。
  • フィールドがfinalでなく、頻繁に書きかわる。

……こんなのデバッグしたくないです。

どうすれば?

Java入門ではこんな感じで書きました。

もしインスタンスメソッドを実行する必要があるのならば、privateメソッドやfinalメソッドのような 拡張されないメソッドにできないかを検討し、対象のメソッド内で他のメソッドを呼び出さないように気をつけましょう。

書いたことは書いたままなのですが、まだ他にも考えられます。

提供側として、どうすればよいか

もし実装クラスで拡張することを想定したインスタンスメソッドを、コンストラクタでどうしても実行したいのならば、どうすれば良いかを考えてみます。 まず、そのメソッドが何をするための拡張ポイントであり、どういうタイミングで実行されるかなど ドキュメントをしっかり書いてください 。 そして、一切のメンバを使用禁止にします。これは三階層以上の継承がある場合、二階層目のコンストラクタで初期化されるフィールドやそれを使用するメソッドが正常に動作しないタイミングで呼ばれてしまうためであり、そのことを具象化しようとしているクラスでの検知が困難だからです。 その上で、メソッドで使用する値は 全て メソッドの引数で渡しましょう。

これでようやく、気をつけて使っていれば大丈夫な可能性のある物体になるかもしれません。 しかし、間違った使い方のできるものは、間違った使い方をされるものです。 要約すると「やらせるな」ということです。考え直しましょう、真面目に。真剣に。悪いこと言わないから。

利用側として、どうすればよいか

さて、利用側の視点でどうすればいいかには触れてきませんでした。

これは いくら利用者が気をつけても、安全に設計できていないものを、安全に使用することはできない からです。 単純なケースであればテストコードなどで比較的容易に検出はできるのですが、「さらに複雑にした(略」あたりで書いているものは辛いです。

フレームワークやライブラリのコードを読むことは推奨したいのですが、必須ではありません。 特に仕事ではコストは確保されないでしょうし、そういうスキルも求められないでしょう。 なので、不具合に気づいたら修正依頼をするか、迂回するか、パッチを当てるくらいでしょうかね。

あとがき

Java入門 第2章「クラスを理解する」の最後の方に書いた コンストラクタでは注意してメソッドを使用する を掘り下げてみました。 コードある方がわかりやすいかな。どうだろう。どっちでもわかりにくいよ、と言われたらごめんなさいとしか言いようがない。 しかし全部このノリで書いたらページいくらあっても……難しい。

出版されてから1年経ちますが、内容はまだ古くなってません。 そのなかで、こんな感じの内容を入門と言い張ってます。入門だよ、うん。

バージョンアップ時に互換性を損ねてしまう変更

Java

あるいは、利用者にバージョンアップをためらわせる変更の手引き。

前置き

うっかり互換性を損なってしまう変更について書いてみます。

知ってたらやらかさないし、なんてことのない事なのだけれど、 知らなかったら何が駄目なのかわかりづらいし、 原因を突き止めるのとかも難しいのかもしれない。と思ったので。

互換性の話なので、ライブラリやフレームワークなどの提供側としての変更になります。

動かない、けど再コンパイルすれば動く

こんなコードがあって、

interface Hoge<T extends java.io.Serializable> {
    T method();
}

これを使っている、こんなコードがある。

class Hogera {

  public static void main(String... args) {
    Hoge hoge = new Hoge<String>() {
      @Override
      public String method() { return "HOGE"; }
    };

    System.out.println(hoge.method());
  }
}

コンパイルして実行すれば、まあ普通に動くよね。

% javac Hoge.java Hogera.java
% java Hogera
HOGE

ここで、元のコードをこう変更しちゃう。

interface Hoge<T> {
    T method();
}

Hoge.java だけ再コンパイルして実行すると、動かない。

% javac Hoge.java
% java Hogera
Exception in thread "main" java.lang.NoSuchMethodError: Hoge.method()Ljava/io/Serializable;
  at Hogera.main(Hogera.java:9)

使う方のコードも再コンパイルするだけで動く。

% javac Hoge.java Hogera.java
% java Hogera
HOGE

説明

Javaは戻り値の型までを含めてメソッドは識別されます。 で、ジェネリクスで境界を使用していると、境界の型で扱われます。何もしていしてないと java.lang.Object ですね。 こういう時に型引数は考慮されません。つまり、 method()LT とかにはならないの。

分かりづらくするためにジェネリクス使ってるけど、単に戻り型を拡げるだけでも十分だったりする。

String method(); // 変更前
Object method(); // 変更後(違うメソッドになる)

昔、似たような事を書いた(しかしタイトル微妙だな……)のだけれど、 正直なところ当時の私の見通しは甘くて、単にビルドツールを使えば解決するって問題ではありません。 今回もjavaファイルを直接扱っているから分かりづらいのだけれど、たとえば Hoge がjarで、 知らない誰かが作っているものだったら、一緒にコンパイルーなんてしませんよね。

こういう変更が入っているかも、と思うとバージョンアップできなくなります。 たまに、依存ライブラリ間でこういうことが起こったりします。 その瞬間のソースを眺めて脳内コンパイルしてると普通に動いちゃうので、知らないと原因特定が難しかったりする困った話。 クラスファイルを読んでたらわかるだろうけど、普通は添付されてるソース読むよね?

動く、けど再コンパイルできない

こんなコードがあって、

class Fuga {

  static void method(String str) {
    System.out.println("FUGA");
  }
}

これを使っている、こんなコードがある。

class Fugera {

  public static void main(String... args) {
    Fuga.method(null);
  }
}

コンパイルして実行すれば、まあ普通に動くよね。

% javac Fuga.java Fugera.java
% java Fugera
FUGA

ここで、元のコードをこう変更しちゃう。

class Fuga {

  static void method(String str) {
    System.out.println("FUGA");
  }

  static void method(Number str) {
    System.out.println("FUGAGA");
  }
}

Fuga.java だけ再コンパイルして実行すると、これは普通に動く。

% javac Fuga.java
% java Fugera
FUGA

使う方のコードも再コンパイル……できない。

% javac Fugera.java
Fugera.java:4: エラー: methodの参照はあいまいです
    Fuga.method(null);
        ^
  Fugaのメソッド method(String)とFugaのメソッド method(Number)の両方が一致します
エラー1個

仕方ないので修正する。

class Fugera {

  public static void main(String... args) {
    Fuga.method((String)null);
  }
}

ダサい。。。 けれど、これでコンパイルできるようになるし、コンパイル後は元通り動作する。うっかりNumberにキャストしたりすると動作が変わるから、「とにかくコンパイルが通るようにすればいい」みたいな対応をすると二次災害になります。 バグ修正時のバグ混入率は通常よりも高いって言いますし、慌てずに落ち着いて対応しましょう。

説明

nullなんて嫌いだ! 最初のと同じ感じだったりします。Javaコンパイル時に呼び出す先のメソッドをコードよりも厳密に決定します。 メソッドオーバーロードしたとしても別のメソッドとして扱うため、コンパイルできないようなオーバーロードを行っても、 コンパイル後のclassが実行される際は問題となりません。

既存のメソッドを修正するときは気をつけられるけれど、 メソッドを追加して今までコンパイルできていたものができなくなるってのは、油断しがちかもしれない。 そしてまだ同じクラスなら話は簡単なのだけれど、たとえばインタフェースに同じ名前のdefaultメソッドが足されたら同じことが起こる。 メソッド足すときも、やっぱり注意しなきゃです。

動作するかと、コンパイルできるかについて書いた。 2軸があるなら、4パターン出るから、あと2パターンも当然あります。 同じように書こう……と思ったのだけれど……

動かないし、再コンパイルもできない

何の互換も残ってないような。変更というより、破壊?

動くし、再コンパイルしても動く

普通に互換性保ててるから問題ないよね?

互換性、互換性、、、

現実で見たことのあるものから二つを挙げてみたけれど、もちろん互換性を損ねる変更なんてのはこれだけではありません。 というか、変更は必ず何かしらの互換性を損ねるでしょう。 先に挙げた通り、具象メソッドの追加も安全ではありません。 可視性を緩めることで損なわれる互換性もあります。

こういう変更をしてしまうと、一番最初に書いたように、利用者はバージョンアップをしたくなくなります。 すなわち、動いているものを変更したくなくなります。 なので提供側ならば全力で避けねばなりません。

だからといって、ありとあらゆる互換性を維持するなんて愚かな目標を立てるべきだと言いたいわけではありません。 それは変更を、つまり成長を阻害することとイコールになります。

そんな役に立たない妄想よりも、 変更がどのような互換性を損ねるかを把握し、 問題があった時にどう対応すれば良いか、その対応にどのくらいかかりそうか とかを 考えといた方がいいんじゃないかな、と思うわけです。

Javadocに何を書こうか

Java

これは Java Advent Calendar 2015 の 16 日目の記事です。

昨日は @yukung さんの Java で引数の null チェックで迷った話 でした。明日は @mdstoy さんです。

ちなみに過去のJavaアドベントカレンダーで書いたもの。

……2013年は書いてないのか。そうか。

前置き

3年前になりますが、コメントについては書いたことがあります。

たまにスライド見返したりするのだけれど、今でもそれほど主張は変わらない感じです。

で、先に挙げた記事はインラインコメントがメインとなっていますので、 今回はドキュメントコメントについて書いてみることにします。

Javadocと言えば

Javadocと言えばHTMLのあいつ。 JavaDocとか言ったり、javadocというツールのことだったり、 Javadocが何を指してるのかよく分からなくなることもしばしばあるけれど、 とりあえずそのことについては考えずにここではJavadocの表記で統一します。

Java SEのAPI仕様は見たことあるはず。

HTMLで出力したものをWebブラウザで見るので、 コメントの本文はHTMLタグでわかりやすくマークアップしなければならない。

また、Javadocタグを使えることろは積極的に使う。 そうすれば、ドキュメント間のリンクとかもやってくれる。 タグは頑張って覚えよう。そんなに種類もないし。

読み方を考えてみる

Javadocコメントを読む方法は以下の3つに大別できる。

一つは先にも挙げたように、インターネットを介して閲覧する場合。 Java SEやOSSライブラリのドキュメントを読むときはこの形が多いだろう。 また、ドキュメントの記述量が多い場合、IDEで読むのはつらいのでこの読み方をする。

次に、IDEで使用するクラスやメソッドのドキュメントを参照する場合。 この用途では、メソッドのコメントを読むことが主になる。 HTMLで読むものと対象は被るが、コーディング中ならばこちらの方法で読むと思われる。 利用するライブラリのソースが必要だけれど、たいてい xxx-sources.jar は手に入るから心配いらない。

最後に、ソースコードを直接見る場合。 自分たちで開発しているコードのドキュメントコメントはこの形で読むことが多い。 というか、わざわざHTMLで見るなんてしない感じ。 APIとして利用を想定されていないクラスやメソッドのコメントを読む場合もこれになる。 この見方だと、ドキュメントコメント以外のコメントやコードも目に入ってきます

書くことを考えてみる

では何を書けばいいかだけれど、昔はこんなこと書いてた。

このコメントに書かれていて嬉しいことは「何が達成できるか」です。どのように使うと、どうなるかをさくっと把握できるのがベストです。 このコメントを読む人がコードを読むことはそれほど考えなくていいです。

これは一番目、二番目の読み方をする時に言えることで、 三番目の読み方をする場合はコードと並べて読むこともあり、書く内容も変わる。 書く内容は非ドキュメントコメントに近いと思われ、実装理由やコードの要約が適切かもしれない。

読み方から書く内容は決まるかなと思ったのだけれど、読み方分類では書く内容を考えづらい。 なので、読み方よりも読者視点で書くことを考えてみることにする。

読者を考えてみる

コメントの想定読者は利用者と保守担当者くらいが考えられる。 これらの想定読者によって、書く内容も変わってくるはず。

想定読者が利用者、つまり公開APIのドキュメントコメントは、 それが何ができるもので、どのように使い、何に気をつければ良いかを記述する。 サンプルコードがあると良いことも多いのだけれど、 コメントはコンパイルできないし、基本的にリファクタリングに追随して修正されたりもしない。 ゆえに嘘になりやすく、誤ったサンプルコードを提示してしまう危険と隣り合わせになる。 それでもあって助かることも多いので、メインとなる公開APIには書いていきたいと思う。

想定読者が保守担当者、つまり公開APIを除く全てのドキュメントコメントは、 それが何ができるものかは同じだけれど、設計判断や拡張時に気をつけるべきことを記述する。 関連が強いクラスへのリンクをしっかり書いておくと助かることも多い。 privateのドキュメントコメントを書く場合、ほぼ間違いなく保守担当者向けだろう。

ドキュメントコメントにHTMLを使うべきか

素直に「JavadocコメントはHTMLでマークアップするもの」とやってしまうと、 主となる読者が「そのコードを保守する人」であるならば、HTMLは邪魔になる可能性が高い。 人間の目はHTMLを解釈しないので、プレーンなテキストの方が読みやすい。 また、コードを修正する時もHTMLタグを書くのは面倒だったりする。

想定読者が保守担当者のドキュメントコメントにHTMLを使用すると、苦労して書いて、苦労して読んで、苦労して修正することになる。 誰も嬉しくない。 そんなことがあるので、「HTMLを使うべきか」と問われると「状況によるし、使わなくてもいいんじゃないかな」になる。

とはいえHTML的に不正な状態だと文句言われるし、多少配慮はしたほうがいいかも。

あらためて、何を書こうか

Javadocに何を書こうか。

どうせ書くなら役にたつものがいいよね。 役に立てる人によって、書いてて欲しいことが変わるよなーとか、 たぶんプロダクトの性質によっても変わってくる。

でも「何を書くか」なんてところこそ、しっかり考えるべきなんだと思う。 考えて出した答えなら大丈夫なはず。 「書かなきゃいけないから書いた」だと、微妙なコメントになってること請け合い。

……色々書いたけど、結論が締まらない。まぁいいか。

ここまで書いてきたこととかは関係なく書くべきものもある。バージョンとかね。 この辺りはJavadocタグで書けるので、一通り眺めてどれを使うか確認しておくのが良いです。

JavaDoc.Next

あ、Javadocといえば JavaDoc.Next とかいうのもありますね。 詳細はよく知らないけれど、JDK9に入るみたいです。

JavaアドベントカレンダーなのにJavaっぽくなくて焦ったから、 JEPとか出して誤魔化しているわけではない。