BT

最新技術を追い求めるデベロッパのための情報コミュニティ

寄稿

Topics

地域を選ぶ

InfoQ ホームページ ニュース コンパイルとドキュメントの出会い

コンパイルとドキュメントの出会い

ブックマーク

原文(投稿日:2021/05/03)へのリンク

OpenJDKコミュニティは、APIドキュメントにコンパイル可能なソーススニペットを追加する方法としてJEP-413を提案している。このアプローチにより、例に取り組むメンテナンス担当者のの役割と、ワーキングコードをコピーしたい読み手の役割が簡素化される。

コードをドキュメントスニペットとしてコンパイルするアプローチは、Azure SDK、R言語、NetBeans、GraalVMなどの主要なプロジェクトですでに使用されている。ドキュメントを使用してカスタムプロジェクトに取り組んでいる開発者は、NetBeansアーキテクトであるJaroslav Tulach氏のCodeSnippet4Javadocによって、既存のプロジェクトを活用できる。

GraalVMプロジェクトリーダーのThomas Wuerthinger氏は「これは素晴らしいイニシアチブである。現在、カスタム開発されたソリューションを使用して、GraalVMドキュメントにスニペットを作成している...」と宣言した

会話では、大規模な開発者プロジェクトの共通点が特定された。そこでは、多くのプロジェクトが同様のソリューションに到達し、ドキュメントのエラーを表示および監視するための方法について話し合った。「Azure SDKでも同じことを行いる」と、Azure SDKに取り組んでいるMicrosoftのプリンシパルJavaアーキテクトであるJonathan Giles氏は述べている。また、「適切な代替として機能する場合には、いつかこれに移行することを楽しみにしている」と述べている。JEPはJava Enhancement Proposalの略であり、Javaエコシステムに移行するには、提案に対する投票と、その後、プロジェクトに対しての統合が必要となることを意味する。

コンパイル可能なソーススニペットの利点は、開発者に影響を与えられることである。開発者は、ドキュメントを読んだ後、自身のプロジェクトのサンプルコードで使用できる。開発者がコードをコピーアンドペーストする傾向は業界でよく知られている。StackOverflowはエイプリルフール2021でctrl、c、vの3つのキーを持つパロディーキーボードをリリースした。このジョークではコピー/ペーストのキーボードショートカットをパロディー化したものであり、うたい文句は「良いアーティストはコピーする。優れたアーティストは盗む。最も優れたアーティストはコピーしてからペーストする。」である。

APIドキュメントと、エラーや古い呼び出しをキャッチする方法について、かなり多くの研究が行われている。研究者のSeonah Lee氏、Rinxin Wu氏、Shing-Chi Chueng氏、Sungwon Kang氏は、古いAPIドキュメントを分析および検出するツールFreshDocについて、IEEEを通じて同様の研究を発表した。ドキュメント分析の有効性を分析した研究について、彼らは論文で「40の古いAPI名を報告したとき…開発者は提案の70%を受け入れた」と述べている。

JEP-413のテキストで、開発者がコードドキュメントを作成する方法を簡素化することが目標であると説明されている。しかし、考えられるすべてのエラーを阻止できるわけではない。たとえば、JEPはコードをコンパイルしない。むしろ、開発者は抽出前にコードを検証するためにコードスニペットをCI/CDと統合する必要がある。このプロセスにより、インポートステートメントのような定型文がドキュメントに含まれなくなるが、それでも、見たい人は誰でもすぐに利用できる。

JEP投票が成功すると、ドキュメントのマーク付けと作成に役立つJavaドキュメントツールの将来のバージョンに機能が追加される。投票の成功は、JavaDocなどのAPIドキュメントツールに最も影響を与える。また、Getting Started Guideという共通のトレンドに代わるものとはならないであろう。それは、新しいプログラマーにAPIで何ができ、特定のAPIを見つけるためにプロジェクトのどこを探すかを紹介するものである。

この記事に星をつける

おすすめ度
スタイル

BT