こまどブログ

技術のこととか仕事のこととか。

Java 9 以降の非推奨モジュールに依存したプログラムを動作させる:OpenAPI Generatorで生成したSpringスタブサーバが動作しない場合の対処法

前回の記事で、OpenAPI GeneratorでSpringのスタブサーバのソースコードを生成する方法を紹介した。

ky-yk-d.hatenablog.com

上の記事に記載した手順を手元のMacBook Proで実行したとき、XmlModelPluginに関わるエラーが発生してSpring Bootアプリケーションとして動作しなかった。別の端末(iMac)では正常に動作したので前回の記事では言及しなかったが、調査してみたところわかったことが多かったので、記事として公開することにした。

あらかじめ書いておくが、今回のエラーの根本原因は後述の通り自分がJavaのバージョンに無頓着であったことであり、OpenAPI Generatorの問題ではない。下記の内容は、OpenAPI Generator固有の問題を扱っているものではなく、Javaのバージョンの差異によって生じるエラーのケーススタディ的なものだと思ってもらえばいい。

概要

項目 内容
事象 生成したSpringのスタブサーバが特定環境で動作しない
原因 Java 11 で非推奨のモジュールが解決されなかったため
対応 pom.xmldependenciesJAXB APIを追加する

発生した事象

OpenAPI Genaratorでソースコードを生成したSpringのスタブサーバが動作しなかった。具体的には、下記のような手順でスタブサーバを起動しようとすると、エラーが発生してしまっていた。

実行手順

下記のコマンドを実行し、OpenAPI Generatorによるスタブサーバのソースコードを生成する。

openapi-generator generate
    -i docs/openapi.yaml # 生成元ファイル
    -o generated-sources/spring_stub # 出力先ディレクトリ
    -g spring
    --additional-properties returnSuccessCode=true

STSを開き、Open Projects from File System ...を選択。生成されたソースコードを読み込ませる。

f:id:ky_yk_d:20190113103609p:plain
ファイルシステムからプロジェクトを開く

STS上のBoot dashboardから、読み込んだプロジェクトを選択して起動する。

f:id:ky_yk_d:20190113105011p:plain
Boot dashboard から起動する

発生するエラー

下記のエラーメッセージがコンソールに表示され、アプリケーションの起動に失敗する。

Error starting ApplicationContext. To display the conditions report re-run your application with 'debug' enabled.
2019-01-12 17:17:36.297 ERROR 6665 --- [           main] o.s.boot.SpringApplication               : Application run failed

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'xmlModelPlugin': Lookup method resolution failed; nested exception is java.lang.IllegalStateException: Failed to introspect Class [springfox.documentation.schema.XmlModelPlugin] from ClassLoader [jdk.internal.loader.ClassLoaders$AppClassLoader@512ddf17]
    at org.springframework.beans.factory.annotation.AutowiredAnnotationBeanPostProcessor.determineCandidateConstructors(AutowiredAnnotationBeanPostProcessor.java:262) ~[spring-beans-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.determineConstructorsFromBeanPostProcessors(AbstractAutowireCapableBeanFactory.java:1198) ~[spring-beans-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.createBeanInstance(AbstractAutowireCapableBeanFactory.java:1123) ~[spring-beans-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.doCreateBean(AbstractAutowireCapableBeanFactory.java:541) ~[spring-beans-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.createBean(AbstractAutowireCapableBeanFactory.java:501) ~[spring-beans-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.beans.factory.support.AbstractBeanFactory.lambda$doGetBean$0(AbstractBeanFactory.java:317) ~[spring-beans-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.beans.factory.support.DefaultSingletonBeanRegistry.getSingleton(DefaultSingletonBeanRegistry.java:228) ~[spring-beans-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.beans.factory.support.AbstractBeanFactory.doGetBean(AbstractBeanFactory.java:315) ~[spring-beans-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.beans.factory.support.AbstractBeanFactory.getBean(AbstractBeanFactory.java:199) ~[spring-beans-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.beans.factory.support.DefaultListableBeanFactory.preInstantiateSingletons(DefaultListableBeanFactory.java:760) ~[spring-beans-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.context.support.AbstractApplicationContext.finishBeanFactoryInitialization(AbstractApplicationContext.java:869) ~[spring-context-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:550) ~[spring-context-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:140) ~[spring-boot-2.0.1.RELEASE.jar:2.0.1.RELEASE]
    at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:759) ~[spring-boot-2.0.1.RELEASE.jar:2.0.1.RELEASE]
    at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:395) ~[spring-boot-2.0.1.RELEASE.jar:2.0.1.RELEASE]
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:327) ~[spring-boot-2.0.1.RELEASE.jar:2.0.1.RELEASE]
    at org.openapitools.OpenAPI2SpringBoot.main(OpenAPI2SpringBoot.java:24) ~[classes/:na]
Caused by: java.lang.IllegalStateException: Failed to introspect Class [springfox.documentation.schema.XmlModelPlugin] from ClassLoader [jdk.internal.loader.ClassLoaders$AppClassLoader@512ddf17]
    at org.springframework.util.ReflectionUtils.getDeclaredMethods(ReflectionUtils.java:659) ~[spring-core-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.util.ReflectionUtils.doWithMethods(ReflectionUtils.java:556) ~[spring-core-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.util.ReflectionUtils.doWithMethods(ReflectionUtils.java:541) ~[spring-core-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    at org.springframework.beans.factory.annotation.AutowiredAnnotationBeanPostProcessor.determineCandidateConstructors(AutowiredAnnotationBeanPostProcessor.java:245) ~[spring-beans-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    ... 16 common frames omitted
Caused by: java.lang.NoClassDefFoundError: javax/xml/bind/annotation/XmlType
    at java.base/java.lang.Class.getDeclaredMethods0(Native Method) ~[na:na]
    at java.base/java.lang.Class.privateGetDeclaredMethods(Class.java:3167) ~[na:na]
    at java.base/java.lang.Class.getDeclaredMethods(Class.java:2310) ~[na:na]
    at org.springframework.util.ReflectionUtils.getDeclaredMethods(ReflectionUtils.java:641) ~[spring-core-5.0.5.RELEASE.jar:5.0.5.RELEASE]
    ... 19 common frames omitted
Caused by: java.lang.ClassNotFoundException: javax.xml.bind.annotation.XmlType
    at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:582) ~[na:na]
    at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:178) ~[na:na]
    at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:521) ~[na:na]
    ... 23 common frames omitted

発生原因

OpenAPI Generatorが生成したソースコードが想定するJavaのバージョンが8であるのに対し、MacBook ProにインストールしているJavaのバージョンが 11 であり、Java 9 以降で非推奨となっているjavax.xml.bindのモジュールが解決されなかったため。

Java 9 以降で非推奨になったモジュール群

(エラーの発生しなかった)iMacにインストールしてあったのがJava 8 であったのに対し、MacBook Proでは、以前遊びでJava 11 をインストールしてあった。下記の記事に拠れば、Java 9 以降ではいくつかのモジュールが非推奨となっており、デフォルトで解決されずに例外が発生してしまう。

javax.xml.bind

今回の場合、エラーの原因となっていたのは、javax.xml.bindというモジュールだった。このモジュールも、Java 9 以降で非推奨となっているものだ。エラーメッセージの末尾をみると、確かにClassNotFoundExceptionが発生していることがわかる。

Caused by: java.lang.ClassNotFoundException: javax.xml.bind.annotation.XmlType
    at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:582) ~[na:na]
    at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:178) ~[na:na]
    at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:521) ~[na:na]
    ... 23 common frames omitted

改めて、エラーメッセージをみてみると、以下のように、XmlModelPluginクラスでIllegalStateExceptionが発生している。つまり、このXmlModelPluiginが、解決されないjavax.xml.bindモジュールに依存していることにより、今回のエラーは発生していたようだ。

java.lang.IllegalStateException: Failed to introspect Class [springfox.documentation.schema.XmlModelPlugin] from ClassLoader [jdk.internal.loader.ClassLoaders$AppClassLoader@512ddf17]

OpenAPI GeneratorとSpringFox

なお、上記のXmlModelPluginSpringFoxの一部であるが、OpenAPI GeneratorのGitHubリポジトリの文書を確認してみると、生成されるSpringのスタブサーバはデフォルトでSpringFoxを利用しているという記載が確かに存在する。

library
    library template (sub-template) to use (Default: spring-boot)
        spring-boot - Spring-boot Server application using the SpringFox integration.
        spring-mvc - Spring-MVC Server application using the SpringFox integration.
        spring-cloud - Spring-Cloud-Feign client with Spring-Boot auto-configured settings.

エラー解消のための対応

Java 8 に戻す……のではなく、前掲の記事にあるように、明示的に「Maven Central 上のアーティファクトを利用するよう依存ライブラリを追加」する。具体的には、下記をpom.xmldependenciesに追加すればよい。

<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
</dependency>

以上の記述を追加してから、Boot dashboardから再起動すると、エラーが発生することなく正常に動作するようになった。ブラウザからAPIにアクセスすると、下記のように表示される。

f:id:ky_yk_d:20190112172255p:plain
http://localhost:8080/detailsにブラウザでアクセスした場合

感想

Javaのバージョンの差異に因って生じるエラーということは思いつかなかった。そもそも自分のマシンにインストールされているJavaのバージョンをあまり意識できていなかった。自宅ではJavaを書くことがほとんどないとはいえ、Javaで飯を食っている人間としては猛省すべき事案だった。「iMacなら動くし、まぁいっか」で済ませてしまわずに、原因を調査したことで左記のことに気づくことができたのが救いか。

今回は、対応として依存モジュールを明示するという方法を書いたが、Java 11 で動作するソースコードを生成できればそれに越したことはない。この点については、そのような変更がOpenAPI Generatorで可能なのかどうかをまだ理解できていないので、また何かわかったら記事にしたいと思う。

OpenAPI GeneratorでRESTful APIの定義書から色々自動生成する

APIの定義を書く:Excel仕様書はもういやだ

RESTful APIを提供するサーバと、そのAPIを利用するクライアント(たとえばSPA)とを並行で開発しようとするとき、まずAPIを定義して、それに基づいてサーバ/クライアント双方の実装を進めようと考えるのは自然だと思う。

そうと決まれば、「API仕様書_20190110.xlsx」と題するファイルを新規作成し、シート別にリソース毎の定義を書き始め・・・てはいけない。せっかくAPIを定義したドキュメントを作成するなら、するのなら、ソースコードの自動生成などの恩恵も受けたい。受けられるはずだ。

少しググってみる。どうやらSwaggerというものを使えばいいらしい。Swaggerに興味を持ったタイミングで、ちょうど書店に平積みになっていた『WEB+DB PRESS Vol.108』の表紙が目に入った。そこには、「スキーマ駆動Web API開発 OpenAPI/GraphQLで仕様からコードもテストも作成」の文字。

WEB+DB PRESS Vol.108

WEB+DB PRESS Vol.108

  • 作者: 中野暁人,山本浩平,大和田純,曽根壮大,ZOZOTOWNリプレースチーム,権守健嗣,茨木暢仁,松井菜穂子,新多真琴,laiso,豊田啓介,藤原俊一郎,牧大輔,向井咲人,大島一将,上川慶,末永恭正,久保田祐史,星北斗,池田拓司,竹馬光太郎,粕谷大輔,WEB+DB PRESS編集部
  • 出版社/メーカー: 技術評論社
  • 発売日: 2018/12/22
  • メディア: 単行本
  • この商品を含むブログを見る

この特集がよかった。この特集では、そもそもOpenAPIがどのような需要に応ずるものなのかから、(この記事では言及しないが)API定義に基づいて自動テストを実行する方法まで、サンプルも用いながら説明しており、入門には最適だった。サンプルコードは下記のGitHubリポジトリで公開されている。

github.com

この特集をきっかけとして、OpenAPI関連のツールを少し使ってみたので、まとめておく。

OAS準拠のAPI定義を書く

「OpenAPI Specification」とは

OpenAPI Specification(OAS)は、RESTful APIを定義するための標準仕様だ。OASにしたがって記述されたJSONあるいはYAMLファイルからは、HTMLドキュメント、スタブサーバやAPIクライアントのソースコードなどを自動生成することができる。テキストファイルなので、Gitなどでバージョン管理をすればdiffを確認することも容易になる。

OASドキュメンテーション

github.com

OASのドキュメントは、上掲のGitHubリポジトリのほか、SwaggerのWebサイトにもまとまったものが存在している。元々、現在のOASのベースとなる仕様はSwaggerという名称で、標準化団体であるOpenAPI Initiativeに所有権が移り、2016年に名称がOASに変更されてからも、開発されてきた周辺ツールの数々はSwagger 〇〇という名称のまま存続している。

インストールなしで使える「Swagger Editor」

Swaggerの周辺ツールのうち、一番わかりやすいのが、Swagger Editorだろう。複数のツールを統合したもので、インストール不要で利用できるオンライン版がすぐ試せる*1。画面の左側にOASに準拠した内容を入力すると右側にリアルタイムでHTMLドキュメントのプレビューが表示されるほか、記述内容に即したスタブサーバやAPIクライアントのソースコードを、上部のメニューから生成することができる。

f:id:ky_yk_d:20190113233854p:plain
Swagger Editor(オンライン版)

VS Code拡張「Swagger Viewer」

簡単な編集であれば、オンライン版のSwagger Editorで事足りるが、実際のアプリケーションのAPIを定義するのであれば普段使っているエディタで編集できた方が都合がいい。そのような需要に対しては、先述の特集記事の中でも紹介されている、Visual Studio Code拡張機能の「Swagger Viewer」が優秀だ。OASの構文エラーを表示してくれるほか、Swagger Editorと同じようにHTMLドキュメントのプレビュー表示にも対応している。

marketplace.visualstudio.com

OpenApi Generatorを使ってみる

Swagger Codegenからフォークした「OpenAPI Generator」

OAS準拠のAPI定義からソースコードやHTMLドキュメントを生成するのは、Swaggerの名を冠するツールの中では「Swagger Codegen」の役割だ。Swagger Editorの画面からソースコードを生成するときにも、このSwagger Codegenが機能している。

Swagger Codegenを利用してもいいのだが、今回は冒頭に掲げた特集で紹介されている「OpenAPI Generator」を利用してみることにする。Swagger Codegenが、かつて仕様としてのSwagger(現在のOAS)を所有していたSmartBear社メンバーを中心に開発されているのに対し、Swagger CodegenからフォークされたOpenAPI Generatorはコミュニティによって開発されている。この辺りの事情については、OpenAPI Generaterのコミッターであり、特集にも寄稿されている @NAKANO_Akihito さんのブログ記事に書かれている。

ackintosh.github.io

OpenAPI Generatorをインストールする

github.com

OpenAPI GeneratorはJava製ツールで、Maven Centralから取得することができる。インストールの方法は様々用意されている。今回は、NPMパッケージ版を利用してみることにした。クライアントの開発でNPMを利用することが多いから、有力な選択肢になるのではないだろうか*2

github.com

インストールは通常のNPMパッケージと同じようにnpm installコマンドを実行すればいい。グローバルインストールしてもいいが、クライアント側のアプリケーションにローカルインストールしておくと、package.jsonのscriptが使えるので便利だと思う。

OpenAPI Generatorを使った自動生成を試す

HTMLドキュメントを生成する

VS CodeのSwagger Viewerでリアルタイムにプレビューすることができるので、YAMLファイルを編集している際はそちらを見ればいい。しかし、APIの定義を見るのにわざわざVS Codeを開くのは面倒だから、手軽に見られる静的なHTMLドキュメントが欲しくなる場面もある。

OASの定義ファイルから、OpenAPI GeneratorでHTMLドキュメントを作成することができる。generateコマンドで、-gオプションの引数をhtmlとすればいい。

openapi-generator generate
     -i docs/openapi.yaml # 定義ファイルの指定
     -o docs/html # 出力先ディレクトリの指定
     -g html 

定義ファイルは長大になるのであえて記載しないが、動作を試したい場合はSwagger Editorにアクセスした際にデフォルトで表示される、Swagger Petstoreをそのままコピーしてみればいい。自分で書いてみたYAMLファイルを元に生成したドキュメントは、以下のようなものになる。

f:id:ky_yk_d:20190113214539p:plain
生成されたHTMLドキュメント

APIクライアントを生成する

APIクライアントの作成にも対応している。HTMLドキュメントを作成するのと同様、generateコマンドを用いる。-gオプションの引数に、生成したい言語/フレームワークを指定してあげればいい。選択できる言語とフレームワークの一覧は、GitHubのREADMEに記載にある通り、多岐にわたっている。特集ではJavaScriptソースコードを作成していたが、下の例では、Angular用のクライアントを生成している。このクライアントの使い方については、後日試してみようと思う。

openapi-generator generate
    -i docs/openapi.yaml
    -o generated-sources/client
    -g typescript-angular
    --additional-properties="ngVersion=7.2.0"

スタブサーバーを生成する

APIの定義中には、exampleとして各データ型の値の例示を含めることができる。この各データ型の値の例を元に組み上げられるレスポンスボディのサンプルは、HTMLドキュメント内で表示されるほか、OpenAPI Generatorで生成したスタブサーバの返却する値としても利用できる。

スタブサーバを用意すれば、クライアントの開発はAPIサーバの実装を待たずに実際の動作を確認しながら進められる。スタブサーバも、OpenAPI Generatorのgenerateコマンドで生成することができる。下記では、Springのソースコードを生成している。

openapi-generator generate
     -i docs/openapi.yaml
     -o ../spring_stub
     -g spring
     --additional-properties returnSuccessCode=true

生成したスタブサーバを動作させるのも難しくはない。STSを開いて、ファイルシステムからプロジェクトを開き、Boot dashboardから起動するだけだ。

f:id:ky_yk_d:20190113103609p:plain
ファイルシステムからプロジェクトを開く

f:id:ky_yk_d:20190113105011p:plain
Boot dashboard から起動する

コンソールで起動が確認できたら、スタブサーバが利用できるようになっている。試しに、ブラウザで今回定義したURIのひとつであるlocalhost:8080/detailsにアクセスすると、下記のようにJSONが取得でき、スタブサーバが動作していることが確認できる。

f:id:ky_yk_d:20190112172255p:plain
5000兆円欲しい

感想

設計書というとExcelという環境で仕事をしてきているので、「YAMLからコードを自動生成する」なんてことはどこか別の世界の営みだと感じてしまう部分があった。また、アプリのソースコードを書くのは楽しいと感じていて、勉強するのもそんなに心理的ハードルがないのに対して、XMLYAMLといった設定ファイルの記述は面白くなさそうなイメージがあり、勉強する際も避けて通りがちだった。

JSONは書く機会がそこそこにあるので、さすがにもう 「気味の悪い拡張子」 だとは思わなくなっているが、YAMLは書いたことがなかったので、いい機会になった。経験を積んでいけば、自動化のメリットも感じられるようになるだろうし、単純に見る機会が増えれば苦手意識もなくなると思う。これからも色々試してみたい。

*1:インストール版もある。

*2:とはいえ、あくまでラッパーでしかなく、Java製ツールであることには変わりはないので、JVMが不要になるわけではない。

ドキュメンテーションコメントからプログラミングを考える / 『エンジニアのためのJavadoc再入門講座』を読んだ

『エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方』を読んだ。

エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方

エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方

ソースコードの書き方、コメントの書き方を説明している書籍は、『リーダブルコード』をはじめとして数多く存在するが、ドキュメンテーションコメントに焦点を当てている書籍は珍しい。

タイトルにあるように、この書籍はJavaにおけるドキュメンテーションコメントの仕組みであるJavadocを扱ったものである。内容も、多くはJava、あるいはJavadoc固有の事柄が中心だ。しかし、広くドキュメンテーションコメントの書き方、ひいてはコードの書き方や設計の考え方にも役立つ内容も多く含まれていた。

Javadocとは?

Javadocは、JavaソースコードからAPI仕様書を生成する仕組みだ。クラスやメソッド等の宣言の上部に/** コメント */という形で記載しておいたコメント(ドキュメンテーションコメント)を元に、コマンドひとつでHTML形式のAPI仕様書を生成することができる。書籍から具体例を引用しておく*1

/**
 * <p>指定された顧客名の合致する顧客の一覧を返します。
 * <p>顧客の姓と名を1文字のスペース(U+0020)で結合し、
 * その結果が引数に指定された顧客名に前方一致した場合、
 * その顧客は結果のリストに含まれます。
 * @param name 顧客名
 * @return 顧客の一覧(順不同)。一件も合致しなかった場合は空のリストを返す。
 * @exception IllegalArgumentException 顧客名が{@code null}
 * または空文字列だった場合
 */
public List<Customer> findCustomers(String name)
  throws IllegalArgumentException;

上のコメントを書くことによって、下記のようなHTML文書を生成することができるほか、IDE(例はEclipse)でマウスカーソルを当てた際に表示されるツールチップの情報を充実させることができる。

f:id:ky_yk_d:20190106214017p:plain
生成されるHTML文書

f:id:ky_yk_d:20190106235851p:plain
Eclipseで表示されるツールチップ

なぜ「ドキュメンテーションコメント」か?

この書籍では、ドキュメンテーションコメントを、通常のコメントとは異なる役割を持つものとして捉えている。すなわち、通常のコメントが「人間がそのソースコードを読むための補助情報」であるのに対し、ドキュメンテーションコメントは、「コードから独立したAPI仕様書として読まれる」ものだというのだ。

ドキュメンテーションコメントはAPI仕様書を作成するためのものであり、記述すべきなのは、「仕様」である。もちろん仕様は、クラスやメソッドの名称や引数(シグニチャ)から推測することもできるし、細かい動きが知りたければ、ソースコードを読めば理解することができる。

しかしながら、シグニチャだけでは(特に特殊なケースの)振る舞いについて情報が不十分である場合が多いし、いちいちソースコードを読むのはコストがかかりすぎる。そこで、ドキュメンテーションコメントという形で仕様についての情報を補う必要がある。

ドキュメンテーションコメントの意義の二側面

プログラムの仕様が、ドキュメンテーションコメントによって明確になることは、多くのメリットを生み出す。この書籍では、下記のようなものが挙げられている。

  • クラスの目的が明確になることで、そのクラスの用途がわかり、再利用性が増す
  • クラスの制約が明確になることで、そのクラスを使ってはいけない局面がわかり、無用なバグを減らすことができる
  • 正しく文書化されたクラスは、利用する側の学習コストを低く抑えられる

これらは、一度作られたプログラムに関わるメリットである。しかし、著者は同時に、ドキュメンテーションコメントの記述対象となるプログラムの作成段階で得られるメリットにも言及している。それが下記の3つである。

  • 設計の漏れや抜けを削減できる
  • クラスやメソッドの設計品質が上がる
  • テストケースの設計が行いやすくなる

この後者の側面が、この書籍の面白い部分だと思う。仕様を明確に表現するドキュメンテーションコメントを書く(書こうとする)と、実装者自身の曖昧な理解、設計の漏れや歪さに気づくチャンスが生まれる。コメントを書く段階で仕様を明確にできれば、テストも書きやすくなる*2

優れたプログラマであれば、ドキュメンテーションコメントを書くまでもなく、漏れや曖昧さのない設計・実装をすることができるのかもしれない。しかし、少なくとも僕のような経験の浅いプログラマにとっては、自分が書こうとしているプログラムについて吟味する機会は不可欠だ。この書籍を読むことによって、自分が意識してなかったプログラミングの観点を知ることができた。

ドキュメンテーションコメントのチェックポイント(抜粋)

ドキュメンテーションコメントを書く際のチェックポイントは、第3章・第4章で数多く挙げられている。一部を抜粋して下に記載しておく。

  • メソッドの引数
    • 典型的な「特別な値」を受け取ることは可能か?
    • 定義域内に「穴」となる値は存在しないか?
    • 受け取ったオブジェクトの状態は変更されるか?
  • メドッドの返却値
    • 定義域のすべての範囲に対して、適切な返却値が定義されているか?
    • 返された値を、呼び出し側でチェックする必要はないか?
  • メソッドのスローする例外
    • 例外が発生する状況がわかるようになっているか?
  • インターフェース
    • そのインターフェースがコラボレーションすべきオブジェクトは明確になっているか?
  • クラス
    • クラスの生成や破棄に、特別な手続きは必要ないか?
    • そのクラスは、他の類似のクラスとは異なる振る舞いをしないか?

出版社のHPで公開されている目次も参考になると思う。

www.shoeisha.co.jp

感想

この書籍は、ドキュメンテーションコメントについて書かれたものだ。しかし、ドキュメンテーションコメントを書こうとすることは、先に述べたように、考えるという営みを伴うものであるし、ドキュメンテーションコメント以外の、ソースコード本体や通常のコメントで書くべき事柄を浮き彫りにすることでもある。多くを学び、また学ばなければならないと感じさせられた。

また、この書籍で一つの考え方として紹介されている「契約による設計」についても、理解を深めたいと思った。外見も値段もゴツいバートランド・メイヤーの『オブジェクト指向入門』は、読みたい読みたいと言いながら読めていない。平成のうちに読めるだろうか。

オブジェクト指向入門 第2版 原則・コンセプト (IT Architect’Archive クラシックモダン・コンピューティング)

オブジェクト指向入門 第2版 原則・コンセプト (IT Architect’Archive クラシックモダン・コンピューティング)

*1:14ページ。

*2:テストを書こうとすることで仕様の漏れが見つかるという逆の流れもあると著者は脚注(11ページ)で記載している。テスト駆動開発に関わる勉強会で紹介されていた、フレームワークやライブラリに対してテストケースを書いてみることで、それらの仕様に対する理解を深めるというアプローチにも通ずるところがある。