JavaOne2013レポート002-Practices and Tools for Building Better APIs(後半)

前半記事はこちらから

JavaOne2013レポート001-Practices and Tools for Building Better APIs(前半) - desi-gneer(designer_engineer)

4# Usableとは

前半に記載したが、Peter氏は、良いAPIの定義として

1.Valuable(always important)

2.Usable(more important if used more)

3.Stable(more important if used more and longer)

を上げている。

API design は human intarface designに似ているとした上で、

APIのUsableを次の5つの項目に分けた。


  • 1.Learnability(学びやすさ)

どれだけ早く仕様を把握してもらえますか？

  • 2.Efficiency(効率的)

一度ユーザがデザインを把握すれば、「すぐに使える」ことが大切と。

  • 3.Memorability(覚えていやすい)

一度使ったら忘れない。そんな設計素敵ですよね

  • 4.Errors rate(エラーの評価がされている)

エラーからの復帰しやすさも大切とのこと

  • 5.Satisfaction(満足できるものであること)

満足、してますか？


改めて言葉にすると当たり前の要素もあると思いますが、

この5つすべてに不満が無いAPIを作れる人もなかなかいないのでは。


5# Internal Designについて

内部設計については

Example first

Example is most important in API documentation.

と、サンプルがとにかく大事だと述べていた。

これは自分も非常に共感する所で、

APIのドキュメントをみる時はやっぱりまずはサンプルをみます。

あー、大体こんな感じか。。ってのが分かりますもんね。

なければ仕様書を見るわけですが。。

サンプルが充実してると凄く嬉しいですよね、使う側にとっては。

仕様書読めば分かるでしょうというのは、少なからずエゴも含まれていると感じます。

サンプル見ただけで殆ど使い方が分かるAPIは、やっぱり使いやすい。

続いて、

concrete use case,

usability check(具体的なユースケース、ユーザビリティのチェック)

が大切と。

2.Usable(more important if used more)

の

1.Learnability(学びやすさ)

2.Efficiency(効率的)

3.Memorability(覚えていやすい)

を意識してといった所でしょうか。


6# Shapeするために(null check)

繰り返しですが、Peter氏はAPIをshapeすることの重要性を度々述べている。ここから、コードレベルの話に入っていく。
まずは、

Smaller APIs are easier to use.(小さければより使いやすい)

  • less classes
  • less methods
  • less parameters

と。当たり前ですよね。少ない方が使いやすい(usable)、安定する(stable)

本セミナーでは、Null check/Lambda式を例に上げていくつかのコード比較を例に出していました。

pubric void sample(String param){
    if (param == null){
        return;
    }
    //処理
}

こんなコード、書いてませんかって。
あります。うちにはあります。。(涙目
認識してるけど、改めて突きつけられると
JavaOneでの発表ということもあって、
良い例として、
Java SE7で追加されたrequireNonNullを使ったコードが挙げられていました。
Objects (Java Platform SE 7 )
コードが少し短くなることもさることながら、
エラーはちゃんと起こしましょう。

ってのも大事ですよね。

pubric void sample(String param){
    Objects.requireNonNull(param);
    //処理
}

もちろん、googleのguavaを使って、checkNotNullでもいいと思います。

pubric void sample(String param){
    checkNotNull(param,"this parameter must be null hogehoge");
    //処理
}

こっちだとNullPointerException発生時のエラーメッセージ足せるし。


また、JSR305/FIndbugsを利用して、アノテーションを利用して想定外の
null関連の問題が発生を防ぐことも大切と。
@Nonnull: nullを許容しない
@Nullable: nullを許容する
@CheckForNull: nullになる可能性を考慮してチェックを促す
参考:
FindBugs の @NonNull @CheckForNull アノテーション - あるプログラマの日記

話を聞きながら、当たり前だよねと思いつつ胸が痛む自分が。。
基本、、なんですよね。これは。

続いて、基本的にNullを許容しない方針を前提に、
Nullを許容しないInterfaceを作成して、各クラスに
@ParameterAndReturnsAreNonNullByDefalut
のようなアノテーションをつけると、より管理しやすくなるとのこと。
たしかに。

7#Shapeするために(lambda式)

同じくコードをShapeさせる上でLambda式は威力を発揮すると
知っての通り、コード量は減ることが明らかだが、
ビジネスロジックが分かりやすくなることで、

Learnability(学びやすさ)

の面でも効果があると。

###編集中###
(一応コード例をのせる予定)

8#Cheat Sheet書けよ！

そして最後に、Cheat Sheet書けよ！といって、例を見せてくれた。
作ろう、、すぐ作ろう。。

f:id:takahiro-f:20130912003837j:plain

9#まとめ

改めて見直しても、基本的な話が多かったです。

見ていて「はいはい、当たり前ですね。」と思う方もたくさんいらっしゃるかもしれませんが、

当日の反響がそれなりにあったことからも、

実際こういったことを徹底出来ていないサービスを抱えている人

は結構沢山いらっしゃるのではないでしょうか。
もちろん、自分もその一人でした。

また、個人的な見解でもありますが、Learnabilityは、頭のどこかでは分かりつつも、実際に形にしては何かをしているとか、

指標の一つとして目標にすることは少ないのではないでしょうか。

こういった視点の大切さを改めて認識出来ただけでも、このセミナーは自分にとって有意義なものでした。

(おわり)

JavaOne2013レポート001-Practices and Tools for Building Better APIs(前半)

※JavaOneのレポートを書くにあたり、

ブログが必要だったのでとりあえず一つ開設しました。

 

JavaOne3日目に聴講した、Peter Hendriks氏の

「Practices and Tools for Building Better APIs」についてのまとめ前半。

 

本セミナーは、表題の通り

「良いAPIとは何か」について考えを深めると共に、

Javaの最新動向とも関連づけてどのような改善が出来るのか述べている。

下記に話の大枠毎に区切ってまとめていく。

 

1# 2つの視点

APIの設計を考える上で下記の2つの立場について考えることが鍵である。

それは

Consumer(APIを使う人)とImplementer(APIを実装する人)

であると。

 

この2つをいきなり並列で出してくることがまず新鮮だった。

我々としては、前者(Consumer)と後者(Implementer)は

それぞれ全く別者として考慮しているからだ。

 

その上で、下記が大切だと述べた。

1.Reuse(再利用しやすいことが大切)

-先を見据えた実装はとても大切である。APIを設計する場合は、そのAPIの将来像、

あるべき姿について考えることが大切だと考える。これを考えれば、コアなAPIほど再利用出来る形に自然と近づくはずである。

 

2.Independent change(独立して変更可能であることが大切)

-これは実際に社内のAPIを担当していて感じるが、

様々な用件で、仕様の変更が求められる機会は多々ある。もちろんそこで仕様を変えるかどうかは別問題だが、柔軟な設計であることで仕様変更に耐えられることも事実。

 

3.Separate concerns(※色々と意味がとれるのですが、リスク分散が大切(としておきます)

-※編集中※

 

2#APIは使う側にとってはブラックボックス

f:id:takahiro-f:20130925070400j:plain

APIは使用する側にとってブラックボックスになってることが往往としてあるという事。

たしかにその通りで、たしかにAPIの先でエラーが起きたときに、

何が原因でエラーなのか全く分からなくて手詰まりになることは少なくない。

社外連携はもちろんのこと、社内の連携でも、色々なものをまたぐほどに良くわからなくなる。。これは胸が痛い

 

そういった理由から、とにかく我々は

 

APIをShape

 

する必要があるとPeter氏。

個人的にshapeって言葉がぴったりだと思いました。

無駄を削ぎ落として、芸術作品のようなAPIを作りたい。 

 

#3良いAPIとは

#1,#2をふまえた上でPeter氏が良いAPIを次のように定義した。

 

1.Valuable(always important)

value = benefit - costs

 

->

ここはやっぱり揺るぎない。

利益を生み出すことはAPIに置いても非常に重要

特に社内APIだと直接ビジネスとの接点が薄い場合もあるので、

忘れがちになる場合もあると思います。コストは計算すると本当に高い

 

2.Usable(more important if used more)

easy to learn

productive

error-proof

 

->

使いやすいこと。easy to learnは改めてとても大切だと認識。

easy to learn(学習しやすさ)がAPIを回収する上でコストの面でも

大切だということを再認識させられた。当たり前のことでもこういう事を項目の一つとして、他の観点と同様に重要だと位置づけることが意識の高さだと感じた。

 

3.Stable(more important if used more and longer)

Able to enhance and grow features without breaking existing consumer code

 

-> 

安定していること。

また、安定する為にどのようなコードを書くかということが非常に大切であるとのこと。

 

2,3についてはコードレベルの話もあるので、その点は後述していきます。

以上で本セッションの前半まとめとさせていただきます。

後半では、良いAPIの定義であるUsableとStableについて実例を

ふまえた説明があったので、引き続きまとめます。