kaizen-from-javadoc

Javadocから考える・はじめる業務改善

JJUG CCC 2018 Spring #ccc_m2

Transcript

1. Javadocから考える・はじめる 業務改善 JJUG CCC 2018 Spring #ccc_m2
2. 自己紹介 1 名前：柚木良介 所属：ＳＯＭＰＯシステムイノベーションズ株式会社 (損保ジャパン日本興亜のシステム会社) 既存システムを刷新する大規模Java開発案件に従事
3. はじめに 2 近ごろ「働き方改革」をよく耳にし、定時退社(ノー残業)の推奨 等、各種施策を実施/推進していると思いますが、労働時間を 削減するだけでは、 そんな声にJavadocの観点から考えてみます。 「やらなければいけない作業は変わらないのに」 「早く退社したって期限に間に合わない」
4. Javadocについて(1/2) 3 (説明不要と思うが) Javaソースから生成し、以下のような画面で閲覧可能なAPIリファ レンス。使用する(作成した)クラスやメソッド仕様について確認できる。 なお今回/** Javadocコメント */は対象外。 ・パッケージ一覧 ・クラス一覧 ・索引 から各クラス/メソッドの説 明にたどることが可能。
5. Javadocについて(2/2) 4 Eclipse等のIDE(統合開発環境)においてJavadocのフォルダやアーカイブを指定するこ とでマウスカーソル上のクラス/メソッド説明を表示する便利な機能あり。
6. Javadoc Search(JEP225/Java9～) JEP: JDK Enhancement Proposal(JDK拡張提案) JSR: Java Specification Request(Java仕様要求) 5 検索欄が追加されインクリメンタルサーチ(文字入力のたびに候補を絞込)可能。 JSR 376: Java Platform Module System (「Project Jigsaw」 とも呼ばれ、Java9で追加された主 要機能。モジュール化により必要な部分のみを利用す ることで軽量化を実現。) 以下の検索(部分一致)が可能。 ・モジュール(※JSR376参照) ・パッケージ ・クラス ・メソッド ・定数 ・@indexで指定した語句
7. Javadoc/Javadoc Searchの課題(1/2) 6 調べたい(ソース上の)クラス、メソッド(API)が どういう機能であるかは調査可能。 しかし、ある機能を実現したい場合どのクラスを使 えばいいかは(知っていないと)分からない。 正規表現 和暦 … java.util.regex.Pattern java.time.chrono.JapaneseDate … (例) クラス名 機能 (英訳や関連しそうなパッケージ/クラス名から推測することは可能だが、非効率)
8. Javadoc/Javadoc Searchの課題(2/2) 7 Javadocに対する全文検索機能が不足 原因 またソースからJavadocを生成してもコーディングの成果物として出力するのみで 活用されることが低いことも。(ソースをGrep検索して見たほうが分かりやすいから？) その結果、(Javadocがあっても)ネット検索 →全文検索を導入しよう！
9. 主な(オープンソース)全文検索エンジン 8 # 製品名 ライセ ンス 言語 URL 1 Namazu GPL C http://www.namazu.org/ 2 Hyper Estraier LGPL C http://fallabs.com/hyperestraier/ 3 Groonga LGPL C http://groonga.org/ja/ 4 Apache Solr Apache Java http://lucene.apache.org/solr/ 5 FESS Apache Java https://fess.codelibs.org/ja/ 6 Elasticsearch Apache Java https://www.elastic.co/jp/produc ts/elasticsearch
10. 身近なもので全文検索できないか？ 9 (オープンソース/商用含め)新規ソフトウェアは ダウンロードやインストールの申請が必要であり、導入 効果の評価等含め時間がかかることが多い。
11. Eclipse Help(Information Center) 10 目次 索引 全文検索 Javaの統合開発環境(IDE)としてよく使用されるEclipseのヘルプ機能に着目。
12. Eclipse Helpの特徴・利点(1/2) 11 1. 「Apache Lucene」を利用した全文検索 →各種オープンソースもLuceneをベースとしており、遜色なし。 2. 検索結果(サマリ)ページではなく本文のキーワードに対して ハイライト(強調)表示 3. 全文検索以外にCHM(Compiled HTML Help)ファイルや Java Helpといったヘルプ同様に以下の機能あり。 ・目次(見出しのツリー構造) ・索引(キーワード・タグ) - インクリメンタルサーチ ・ブックマーク(※) ※ブラウザからアクセスする場合はブラウザのブックマークで代用。 https://lucene.apache.org/
13. Eclipse Helpの特徴・利点(2/2) 12 4.スコープ(検索範囲)や条件指定による絞り込みが可能。 →検索結果が多すぎて目的の資料が埋もれる問題も解消。 (検索範囲/条件は任意の名称で 保存→再利用可能) 5. ファイル配布によるローカル端末利用とともにヘルプサーバとして別端 末からブラウザによるアクセスが可能。 6. Eclipseプラグイン機構によりヘルプの追加・更新が容易。
14. Eclipse Helpの実現方法(サンプル) 13 「ファイル」メニュー→「新規」→「その他」 ウィザードの「プラグイン開発」→「プラグイン・プロジェクト」を選択 数回「次へ」を押下すると「サンプルのヘルプ目次付きプラグイン」あり
15. Eclipse Helpの実現方法 14 <toc label="タイトル"> <topic label="見出し1" href="URL1"> <topic label="見出し1.1" href="URL2" /> </topic> <topic label="見出し2" href="URL3" /> </toc> ◆目次用XML(toc.xml) ※階層構造によってはtocではなくtopicにタイトル記載。 基本的に以下の2ファイルを作成することで実現。 <index> <entry keyword="見出し1"> <topic href="URL1" title="キーワードが同じ場合の別名(任意)" /> </entry> ...(略)... </index> ◆索引用XML(index.xml)
16. Eclipse HelpによるJavadoc検索 15 HTML HTML (Javadoc) Eclipseヘルプ化(目次/索引生成) ということで作ってみました。 JavadocのHTMLファイルから ・パッケージ ・クラス/インタフェース ・メソッド ・定数 のリンク先を抽出 XML XML (目次/索引)
17. Eclipse HelpによるJavadoc検索(目次) 16 ツリー構造にて パッケージ、クラス を指定。
18. Eclipse HelpによるJavadoc検索(索引) 17 (Java8以前においても) Javadoc Searchと同様に ・パッケージ ・クラス ・メソッド ・定数 のインクリメンタルサーチ(前方一致)可能。
19. Eclipse HelpによるJavadoc検索(全文検索) 18 ファイル内のキーワードをハイ ライト(強調)表示。 検索結果一覧 (概要表示も上部のアイコンでON/OFF可)
20. (参考)Doxygen 19 http://www.stack.nl/~dimitri/doxygen/manual/output.html Doxygenを使用することでソースから直接Eclipse Helpを出力可能。(未検証)
21. Eclipse HelpでJavadocが便利に検索できる のは分かったけど、それが業務改善？ 20
22. 情報検索に年間どれくらいの時間を 費やしていると思いますか？ 21 ① ～50時間 ② 50～100時間 ③ 100～200時間 ④ 200～300時間 ⑤ 300時間～ ＜1年間の作業時間＞ 約1,920時間 (8時間/日 * 20日/月 * 12月)
23. 一般的には約150時間と言われています。 22 ① ～50時間 ② 50～100時間 ③ 100～200時間 ④ 200～300時間 ⑤ 300時間～ 情報検索 年間 150時間 約7.8%であり、1日あたり約40分、 1ヵ月あたり約1.6日に相当。
24. 社内における情報検索の課題 23 全文検索 Officeファイルオープン ファイル内検索 クローズ(次の検索結果へ) 情報検索に年間150時間費やす要因として、Officeファイルの検索が 多数の時間を占めている印象。 繰り返し ファイル内検索 ファイル内検索 ファイル内検索 ・検索機能不足。 ・ファイルオープン・表示が遅い。 ・ドキュメントが散在し、在り処が不明。 逐次(Grep)検索の場合には、さらに遅くなる。
25. OfficeファイルのEclipseヘルプ化 24 HTML HTML HTML HTML HTML HTML XML XML (目次/索引) OfficeファイルをEclipseヘルプ化しました。 Officeファイル→HTML変換 PDF PDF MS Office + WSH/JScript (Javaだと以下で変換) OpenOffice or LibreOffice + JODConverter HTML HTML (Javadoc) Eclipseヘルプ化 (目次/索引生成) https://github.com/sbraconnier/jodconverter
26. Eclipse HelpによるOffice検索(例) 25 (目次) (索引) (全文検索) 【目次/索引】 ファイル名(全ファイル共通) ・見出し(章題) - Word ・シート名 - Excel ・スライド・タイトル - PowerPoint HTML HTML HTML
27. ヘルプ化で苦労した点と解決策(1/2) 26 ＜Officeファイル→HTML変換による図ズレ問題＞ 画面/印刷 HTML化の際、枠線などが本来 (画面や印刷)の位置からズレて出力。 HTML
28. ヘルプ化で苦労した点と解決策(2/2) 27 Officeファイル→PDF出力 PDF PDF PDF→HTMLにより図ズレを解消。副次的にOffice以外でもPDFから変換可。 PDFファイル→HTML変換 pdf2htmlEX PDF HTML HTML HTML (Javadoc) XML XML (目次/索引) Eclipseヘルプ化(目次/索引生成) http://coolwanglu.github.io/pdf2htmlEX/
29. Eclipse HelpによるOffice検索の効果 28 「年間150時間」の工数削減(創出) ・知りたい情報に素早くアクセスすることで理解度向上。 ・見つからない悩み時間や問合せ等非生産的な時間の短縮。 ・やるべき作業に注力でき、生産性向上。 ・既存ドキュメントを有効活用。新規資料も使い慣れたソフトで可能。 ・検索機能不足。 →Eclipse Help機能による充実した検索手段を提供。 ・ファイルオープン・表示が遅い。 →HTML化によりOffice/PDFのアプリケーション起動やJavaScriptによる変換処理なく、 シームレスに高速表示。 ・ドキュメントが散在し、在り処が不明。 →HTML変換のためにファイルを一か所に集める必要があり、ドキュメント散在が解消。 (GitやSubversion等のバージョン管理による一元管理も可能になる。) 結果 (※未検証だが、以下が期待できる。)
30. おわりに(ご提案事項) 29 業務改善の一施策としてEclipse HelpをJavadocおよび Office文書の検索に利用してみてはどうでしょうか。 身近なところで試行し、(よければ)適用範囲を拡大。 チーム・プロジェクト フロア・部署(拠点) 全体
31. 業務改善の参考になれば幸いです！ 30
32. 31 Javadocから考える・始める業務改善 JJUG CCC 2018 Spring #ccc_m2
33. (補足事項) 32
34. 参考情報/URL 33 【Eclipseのヘルプ・システムを使ってプロジェクトを文書化する】 https://www.ibm.com/developerworks/jp/opensource/library/os-echelp/index.html 【Eclpseでヘルプを集中化する】 https://www.ibm.com/developerworks/jp/opensource/library/os-eclipsehelp/index.html 【Platform Plug-in Developer Guide】(※Eclipse Help内) > Programmer's Guide > User assistance support > Help > Reference > Extension Points Reference ・org.eclipse.help.toc ・org.eclipse.help.index ・org.eclipse.help.criteriaDefinition ・org.eclipse.help.base.searchParticipant 【第1回 Eclipse ヘルプにJava APIリファレンス・マニュアルを編成する方法】 https://www.ibm.com/developerworks/jp/rational/library/07/0320_alupului/ 【第2回 JavaTOCドックレットを使って生成するEclipse Javadoc APIリファレンス構造】 https://www.ibm.com/developerworks/jp/rational/library/07/1225_alupului/ 【第3回 JavaTOCドックレットとANT を実行して生成するEclipse Javadoc APIリファレンス構造】 https://www.ibm.com/developerworks/jp/rational/library/08/0115_alupului/
35. (参考)Helpサーバ起動/終了、アクセスURL 34 > java -classpath <Eclipse>/plugins/org.eclipse.help.base_<バージョン>.jar org.eclipse.help.standalone.Infocenter -eclipsehome <Eclipse> -command start -port <ポート番号> > java -classpath <Eclipse>/plugins/org.eclipse.help.base_<バージョン>.jar org.eclipse.help.standalone.Infocenter -eclipsehome <Eclipse> -command shutdown http://<Helpサーバのホスト名やIPアドレス>:<ポート番号>/help/index.jsp 【Eclipse Helpサーバの起動方法】 【Eclipse Helpサーバの終了方法】 【ブラウザからのアクセスURL】 (※実際は1行で入力) (※実際は1行で入力)