日々常々

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

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とか出して誤魔化しているわけではない。

ハンズオンイベントに潜む悪魔（黒猫）

イベント

11/15に「Javaでwebアプリケーション入門」というイベントのお手伝いをいたしました。 #javajok で関西Java女子部さんのイベントです。

私は参加者と一緒にライブコーディングをするという大役を仰せつかり、緊張のあまり前日は24時間以上爆睡いたしまして。 おかげでGitHubの草を生やそう運動が54日で止まりました。無念。

会場は @bufferings さんに楽天株式会社大阪支社のカフェテリアを提供いただきました。最高ですね。広いし綺麗だし。

同会場にて11月21日(土)に Rakuten Technology Conference 2015 のサテライトが行われます。大阪にいながら世界のセッションを聞けますよ！（英語的な意味で）

当日のコトが起こるまで

家を出てすぐに黒猫に横切られました。嫌な予感がぷんぷんしました。

まず、環境構築でドハマりしました。 ハンズオンイベントでの問題となる筆頭は環境構築です。 ただ、Javaの場合はJDKとIDEの準備さえしていてもらえれば、GradleWrapperが他は良いようにしてくれます。 してくれる。そう思っていた時期もありました。参加者が一斉にGradleWrapperを使えば……ダウンロード、すっごいですね。 全然終わりませんでした。

セッション順番を組み替えたり、Gradleを使わずにjarを添付する形にしたり、運用対処でなんとか凌いでハンズオン開始。 準備はできているので大丈夫だと思っていました。各ステップを細かくコミットしたブランチも作って「何かあってもこれを見てもらえばいける」くらいの気分。この準備は前日やる予定だったのですが、残念ながら私の土曜日は夢に飲み込まれたので、仕方なく会場についてから必死にやってました。でも間に合った、いけるつもりでした。

しかし、現実はそうは甘くありません。 本番はAPIサーバーをherokuに立てました。素振りはlocalhostでやりました。検証環境と本番環境が異なると問題が検出できないものです。 ですが素振りの他に、ほぼ同じように作成したサンプルは動作していたので、大丈夫だと思っていました。油断していたのです。

ただでさえ初心者を対象にしたハンズオン。 いくらサポート陣を揃えていても、予定通り進まないのはある程度仕方ありません。 この辺りは織り込み済みで、最悪最後まで行かなくても仕方ないかなーとも思っていました。

起こったコト

ハンズオンの最後の最後。ブラウザで入力したメッセージをつぶやく、よくあるフォーム入力を受け付けるところです。 そこに、以下のようなコードがありました。

Response res = new RestTemplete().postForObject(
        "http://xxxx.heroku.com/yyy",
        param,
        Response.class);

この子がエラーにならずに正常終了しているのに、APIサーバーにはPOSTできませんでした。ちなみにGETの方は普通に動いていたので、タチが悪い。

原因は xxxx.heroku.com/yyy が xxxx.herokuapp.com/yyy にリダイレクトされる動作になっている点。getForXxx はリダイレクトを平然と処理して、リダイレクト先の結果を返してきます。一方 postForXxx はリダイレクトは処理せず（POSTなのでリダイレクトしたらダメだよね）、そのまま301 Moved Permanentlyを空のbodyで受け取って終了しちゃっていました。 この結果になっていることが検出できずに処理は正常終了。最終的には「エラーにならないのに動かない」という不思議な事態となりました。 プロジェクターでスクリーンに画面を映しながら、頭抱えることに……。

結果的には終わる前に解決できて動いたので、それはそれで良いのですが。

言い訳タイム

herokuとかRestTempleteとか普段使ってないのがね……。

postForEntityで受けて、ResponseEntityのstatusCodeを見れば判断つくのですが、postForObjectだと直接オブジェクトが生成されちゃうので、見るタイミングがありません。一応RestTemplateに拡張したErrorHandlerを差し込んで「201 Created 以外ならエラー」とかもできますが、どちらにせよ「初心者向けハンズオン」にあまり複雑なことは持ち込みたくはないので、知っていても入れなかったでしょう。（Springのハンズオンでは無いのです）

素振りの時点でherokuを使っておけば、herokuとherokuappの違いに気付けたかもしれません。アドレスを打つときに手打ちせずにコピペしていれば間違えませんでした。URIを手打ちせず、サンプルと同じく設定ファイルから @Value で取っておけば問題は起きなかったです。どれも実際は起こらなかった可能性ですが、助かる可能性もあるにはありました。

しかし、気付くタイミングや間違えないタイミングは全てスルーして問題は起きるものです。油断大敵……そこまでは結構うまくいってた（つもりな）だけに、残念感が酷かったです。

総括

とても楽しかった。今度から黒猫に横切られたら帰って寝る。

#AsiyanAutomationAlliance をやりました

イベント

kokucheese.com

第一回 AsiyanAutomationAlliance をや っています。現在進行中です。 りました！第二回AAAです。 運営なんですが、超寝坊しました。開始には間に合ったけど、運営業できてない。。。orz 最後まで運営らしいことできませんでした！！

イベント概要

Asiya最大の自動化イベントです。午前2セッション、午後から2トラックで6セッション、最後に1セッション。懇親会はビアバッシュでLT祭り。2トラックは「テスト自動化」と「自動化・ツール」で大きくわけてお送りしました。

自動家(オートメーター)大地に立つ!! 〜オールドタイプの一年戦争〜

出落ちが酷かったので、あんま大丈夫じゃなかった。 話はいつもの三浦一仁氏だったのでよかったのだけど……。話の裏のツイッターも面白かったので、雑にまとめました。

失敗したデモはLTでリトライ。さあどうなるか。

ギアと開発とわたし

読みたいなーと思ってたけどまだ買ってなかったので、話聞きながらポチった。

システムテスト自動化 標準ガイド (CodeZine BOOKS)

システムテスト自動化 標準ガイド (CodeZine BOOKS)

  • 作者: Mark Fewster,Dorothy Graham,テスト自動化研究会,伊藤望,玉川紘子,長谷川孝二,きょん,鈴木一裕,太田健一郎,森龍二,近江久美子,永田敦,吉村好廣,板垣真太郎,浦山さつき,井芹洋輝,松木晋祐,長田学,早川隆治
  • 出版社/メーカー: 翔泳社
  • 発売日: 2014/12/16
  • メディア: 単行本（ソフトカバー）
  • この商品を含むブログ (3件) を見る

話の中で数式の紹介があったのですけど、そのいじり方の紹介がとても面白かったです。噛み砕いて何かのネタにしたいなー。

まとめ

自動化と一言で言っても、それを使う相手によって求める部分は違うし、違って良いし、それに応えてこそ。自動化も普通の開発と同じところあるなー、というTABOK読書会で話してたことを再確認できたりしました。やばい、進歩ない私。

てことで、個人的なベストセッションは @moririring さんのでした。

非公開ひゃっはー。