Lazy Diary @ Hatena Blog

PowerShell / Java / miscellaneous things about software development, Tips & Gochas. CC BY-SA 4.0/Apache License 2.0

エンタープライズアプリケーションの開発ドキュメント作成で気をつけていること

エンタープライズアプリケーション*1を開発するときに、開発方針(従うべきアプリケーションアーキテクチャの説明から、ライブラリ的なプログラムの使い方までいろいろ)を文書化する役目がよく回ってきます。

「このライブラリにはどういう機能があるの?」「この機能はどう使うの?」を中心に書いた一般的な技術文書と、エンタープライズアプリケーション向けのドキュメントとでは、書くべき内容や書くときに気をつけるポイントがずいぶん違うなぁ(しかもあんまり明文化されてないなぁ)と思ったので、エンタープライズアプリケーション向けのドキュメントを書くときに必要な内容をメモしておきます。

ドキュメント体系に追加する

プロジェクトのドキュメント体系に含まれていない資料は、プロジェクトの正式なドキュメントではありません。正式でないドキュメントの内容に基づいて実施した行動の責任は、誰も肩代わりしてくれません。責任はすべて自分がとる必要があります。イヤですよね(そうでしょう?)

ドキュメントを作成するときは、まずドキュメント体系に追加しましょう。プロジェクトの体制中に、ドキュメント体系の保守を担当しているチームがあるはずです。なかったら、プロジェクトマネージャーに報告して、プロジェクト管理計画を修正してもらいましょう。

ドキュメント体系の編集が面倒*2な場合は、既存のドキュメントの「別紙」とか「付録」とかにすることを検討しましょう。よく、プロジェクトの共通ドキュメントに「別紙」が大量にあるのを見かけますが、これが理由というケースが時々あります。

対象読者を書く

プロジェクトのメンバーには、目を通さなくてはいけないドキュメントがいっぱいあります*3。そんなメンバーが、ドキュメントについてまず知りたいことは「これ読まないといけないの?」「これ知らないといけないの?」です。この点が示されていないドキュメントは、一目だにされないこともしばしばです。

ドキュメント体系には、対象読者も合わせて記載しましょう。分量の多いドキュメントでは、章ごと・節ごとに対象読者が分かるアイコンを付けるのも効果的です。

使わないといけないか書く

ここで「使わないといけない」というのは、「あなたが責任を負う成果物を作成する際には、このドキュメントに書いてある内容を守らなくてはいけない」という意味です。

「これ知らないといけないの?」をクリアしたら、次は「これ使わないといけないの?」「これ使わないとどうなるの?」が主要な関心事になります。「知らないといけない」けど「使わなくてもいい」ものなんてあるの?と思うかもしれませんが、たとえばトラブルシュートや、問題発生時の原因切り分け手順などがこれにあたります*4

なお、ちゃんと「これ使わないといけないの?」が分かるドキュメントを作っていても、「これ使わずに作っちゃったんだけど、許してもらうにはどうしたらいいの?」と言われることもしばしばです。避けたい状況ですが、これも文書化しておきます*5。また、将来のために「これ使うのをやめたいんだけど、何をどうカバーしたらいいの?」が必要になることもあります。

誰の責務か書く

「これ使わないといけないの?」に対する答えは、大きく分けて「はい、この処理の実装はこのライブラリの役割です。このライブラリを使ってください」と、「はい、この処理の実装はビジネスロジックの役割です。あなたが実装してください」に分かれます。

エンタープライズアプリケーション開発のプロジェクト体制では、アーキテクチャの検討や業務色のないフレームワーク・ライブラリの実装を行う「共通チーム」と、ビジネスロジックの実装を行う「業務チーム」とを、比較的明確に分けられます。

この場合、フレームワーク・ライブラリとビジネスロジックとの境目を決めて、どの処理の実装がどのチームの責務なのかを明確に示すことが肝要です。そうしないと、この間に落ちてしまった処理を誰も実装しないままプロジェクトが進んでしまい、共通チームと業務チームとの間で責任の押し付け合いが始まります*6

何のための機能か書く

フレームワークやライブラリに「どういう機能があるの?」「どう使うの?」を書き始める前に、「何のための機能なの?」を示しておいた方が安全です。業務チームのメンバーが、どういう時にこの機能を使えるかを知るための取っ掛かとなります。また、ライブラリの開発者の意図を伝えることで、想定外の使い方をされてしまうのを避けることができます。これは、業務チームのメンバーがマズい実装を作り込んで、プログラム不良が頻発するのを避ける効果があります。

場合によっては「何のための機能ではないか」を書くこともあります。ライブラリの開発者の意図を伝えても、使いたいように使ってしまう開発者というのはどうしてもいるものです。既知の制約がある場合は、明示しておくことでライブラリの開発者を無茶な要求から守ることができます。

機能や使い方を書く

ここまで来て初めて「どういう機能があるの?」「どう使うの?」を書くことになります。

使っていること・いないことの調べ方を書く

必要に応じて「この処理を必ず書かないといけないなら、書いていることをどうテストするの?」「この処理を書かないといけないのに書いていない(ルールを守っていない)ことは、どうやったら調べられるの?」が分かるための資料も作ります。

テストで確認すべき観点*7や、チェック用の静的解析ツールの使い方と警告メッセージを示します。

場合によっては「このアプリケーションの開発で守らなければいけない点はぜんぶでいくつ?」が分かる資料を求められることもあります。これは、業務チームを取りまとめる責任者が、自分のチームの成果物をチェックするための手順として求めてくるケースがちょいちょいあります。

*1:ここではいわゆるギョーミーなソフトウェアを想像してください

*2:ドキュメント体系を体系図として視覚化している場合はとっても面倒

*3:To do our work, we all have to read a mass of papers. (Winston Churchill)

*4:成果物の作成に際して前もって読んでおく必要はなくて、トラブルに遭遇したら必要な部分だけをその都度読めばいい

*5:文書化しておかないと、後任者が見たときに、問題があるんだかないんだから分からなくなります

*6:【余談】誰の責務で実装するか決めるときの私なりのコツは、何でもフレームワークで面倒を見るよりは、業務チームがビジネスロジックで実装する(あるいは、ビジネスロジックからライブラリを明示的に呼び出す)側に寄せることです。この際、多少ステップ数が増えても構いません。

業務チームは人数が多いため、アーキテクチャに対する理解を全体に浸透させるのに手間がかかります。ビジネスロジック中に、フレームワーク的な処理も一部含めて実装するのは、コードを「上から見ていけば、必要な処理が一通り書いてある」状態にでき、アーキテクチャを理解させやすくする効果があります。またフレームワーク的な処理に変更が必要になった場合、実装の変更とテストの両方が業務チームに閉じることから、業務チームの判断で作業を進めることができ、業務チームの人数の多さもあってリカバリーが効きやすくなります。

増えてもいいステップ数の「多少」がどの程度かは、システムの保守期間、アプリケーションの総ステップ数、プロジェクトのリスク費の大きさなどを見て決めます。総ステップ数が1%増えるだけならいいですが、5%増えるとなると考えものです。

*7:加えて、その観点を何の単位(画面単位で1度テストすればよいとか、イベント単位にテストする必要があるとか)でテストするかも必要です

Parasoft Jtest can't ignore Lombok-generated methods/fields

Problem:

When you execute static analysis Java sources with Lombok by using Parasoft Jtest, you have to delombok the sources because of Jtest can't handle Lombok's compile-time generated methods/fields.

Additionally, Jtest raise alerts with Lombok-generated methods/fields, like the field logger generated with @Slf4j annotation.

Reason:

It seems to be by design.

Parasoft Jtest can handle generated code with comment like // parasoft-begin-suppress and // parasoft-end-suppress. But this feature is not supported by Lombok*1.

In Lombok side, delombok command can generate @lombok.Generated annotation to identify Lombok-generated methods/fields. But this feature is not supported by Jtest for now *2.

Solution:

Just identify alerts for Lombok-generated codes by hands, and ignore them.

*1:https://github.com/rzwitserloot/lombok/issues/2237

*2:We had send feature request multiple times since 2017, but it is not implemented in 2019

「プログラミングできるのが普通の若者たち」のレベル感

UR都市機構 Open Smart URのコンセプトブック「UR 2030」*1では、「プログラミングできるのが普通の若者たち」という2030年の若者像を示しています。

では、この「若者たち」とは、具体的にどういう人たちから構成されるのでしょうか? SSP*22030(階層と社会意識全国調査)とSSM*32030(社会階層と社会移動全国調査)が行われたとして、「日常的にプログラミングを行う」と答える層はどの程度の割合で、またそのプログラミングの程度はどういったものなのでしょうか?

そう考えると、きっと「プログラミングできるのが普通の若者たち」イコール「Googlerみたいな人たちが若者人口の大半を占める」ではないだろうなぁと思うわけです。

これまでは、プログラミングを習ったことのない人が大半なので、プログラマのレベルとその人数分布は以下のようになっていると思われます。

f:id:satob:20200105020622p:plain

一方、みんながプログラミングを習い出した後は、「人間の能力はおおよそベル型カーブに沿う」という前提に従うとすると、おそらく以下のような分布になると思われます。

f:id:satob:20200105020626p:plain

この推測通りになれば、「プログラミングできるのが普通」になる前と後とでいちばん増えるのは、グラフの右端にいるようなコードをバリバリ書ける人ではなくて、グラフの真ん中くらいの人になるわけですね。

ここで「このグラフの真ん中くらいの人って、具体的にはいったいどのくらいのレベルなんだろう?」とと考えると、きっとこのレベル分けでレベル10くらいに位置するんじゃないかと思うんですよ。 satob.hatenablog.com

他の指標で言うなら、AtCoderで言うと灰色と茶色のちょうど中間くらいの人が増えるわけですね(茶色が上位50%なので)。そう考えると、やはりあまりレベルが高いとは言えません。 chokudai.hatenablog.com

AtCoder緑色や水色の人がモリモリ増えたらそりゃ嬉しいですけど、学校の他の授業と同じ話で、みんながみんなバリバリできるようには、きっとならないですよね。

「プログラミングできるのが普通の若者たち」が増えるということは、一般的な(プログラミングを生業としない)職業に就くのはこういった「平均的」なレベルの人が大半になる、というわけです。また、今後はあらゆる業種で、自前でプログラムを書くことが増えていくのではないかと思われます。そう考えると、

  • 平均的なレベルの人に、どうプログラミングを教育していくか?
  • 平均的なレベルの人が書いたコードをいかにメンテナンスしていくか?

といった点が、プログラミングを生業としない企業での課題になっていくのではないか(また教育に関する研究の大きなテーマになっていくのではないか)、と考えるわけです。

「詳細設計書」の目指すところと戸籍情報システム標準仕様書

日本の各自治体で行われている戸籍事務は法定受託事務です。ですから、各自治体で実施する事務の内容がバラバラでは困ります。

そのため、戸籍情報システムを開発するベンダー向けに、法務省が「戸籍情報システム標準仕様書」(標準仕様書)という資料を公開しています*1。この標準仕様書は、ISO/IEC12207:2008(SLCP-JCF2013)における「ソフトウェア詳細設計」のレベルで書かれていて、戸籍情報を保存するファイルの構成や、実装すべきロジックを事細かに規定しています。どのベンダーでも標準仕様書の通り実装すれば戸籍システムが作れますし、どのベンダーが作った戸籍システムでも同じように戸籍事務が行えるわけですね。

戸籍システムを各自治体へ導入するためには、標準仕様書への準拠を法務省に認定してもらう必要があるので、一度開発してしまうとアーキテクチャを変更しづらいというデメリットはあります(システムを作り直すと認定も取り直しになるため)。ただそういったデメリットはあるにせよ、標準仕様書は実際に機能しているように見えます。1600ある日本の各自治体で使われてる戸籍システムが、すべて法務省の認定を通るレベルで同質になってるわけですからね。*2

ソフトウェア開発における、いわゆる詳細設計書は、かなりソースコードに近い内容を書くこともあって、生産性を下げる原因として槍玉に上がることがよくあります。ただ、この標準仕様書こそ、「誰が実装しても同じようになる」という詳細設計書の目指していたものを体現する実例なのでは、と思うわけです。

この詳細設計書は、戸籍事務の種類ごとに処理内容が「全部書いてあって、上から読んだらわかる」*3ような、トランザクションスクリプトの形をしています。やっぱり、開発者のレベルに関係なく実装のレベルを揃えるにはトランザクションスクリプトの形がいいんでしょうかね。

あと、作られたのがかなり昔ということもあり、標準仕様書の内容は基本的にCOBOLで実装することを念頭に置いたような書き方になっています。学生のときにインターンで行った某社では「アーキテクチャ設計さえちゃんとしていれば、ロジックは誰でも書ける」ことを重視して、基幹系業務のビジネスロジックの実装にはCOBOLを採用していました。ちょっと話がズレますが、アーキテクチャ設計とビジネスロジックの設計とを分離できるかできないかが、エンタープライズアプリケーションとそれ以外の境目、という気がしています。

さて、戸籍システムを知っている/作ったことのある会社では、上層部から投げかけられる「戸籍システムではうまくいっているのに、なぜ他の業務では詳細設計書を作らないのか」という問いに反駁できるようになるまでは、「誰が実装しても同じようになる」詳細設計書を作ることを目指し続けることになってしまうのではと思うわけです。その問いに答えるには、やっぱり詳細設計書を作ってデータを集めて分析する必要があって……しばらくは詳細設計書から逃げられそうにないですね!

*1:http://www.moj.go.jp/content/000112223.pdf

*2:余談ですが、総務省では戸籍以外の自治体業務(介護とか住基とか)に対しても標準仕様書を策定しようとしているようです。参考: https://www5.cao.go.jp/keizai-shimon/kaigi/special/reform/committee/20191009/shiryou3.pdf

*3:https://twitter.com/satob/status/1181240183506685952

Amazon Kindle Paperwhiteが4G回線で見られるのはWikipediaだけ

Amazon Kindle Paperwhite (4th Gen)は

  • 内蔵のブラウザでWebサイトが(いちおう)見られる
  • 4Gモデルの通信料はAmazon持ち

と聞いていたので、「TwitterとかをKindleで見るようにすれば通信料が節約できるかも!」と思ったのですが、そうではありませんでした。

Wikipediaだけは、本文中の単語を調べるときにも使うため、4G回線でも見られます。ですが、その他のサイト(Twitterとか)は、Wi-Fi接続しているときしか参照できません。

Wikipediaを一日中見てる!みたいな場合を除いて、通信料の節約には使えなさそうです。