2021.6.2技術ブログ

プレインテキスト形式の設計書で、生産性を向上

ソフトウェア開発におけるバージョン管理ツールのデファクトスタンダードは、Git(https://git-scm.com/ )である。
近年、Gitを用いたバージョン管理の対象に、設計書などのドキュメントを含める取り組みが進んでいる。本記事では、プレインテキスト形式で設計書を執筆しGit上で管理することにより、開発生産性を向上する方法を紹介する。

1. Gitの普及と活用

IT技術者向けQAサイトとして知られるStackoverflowで2018年に実施されたソフトウェアのバージョン管理ツールに関する調査(※1)によると、Gitの利用率は87.2%となっており、明らかにデファクトスタンダードと言えるでしょう。

Gitが活用される以前、複数開発者が並列しソースコードの改良を行う際には、開発者間で修正資材の競合が発生したり、競合を避けるための運用稼働がかかるなどして、生産性が悪化してしまうことがしばしば見受けられました。Gitは分散リポジトリであるため、開発者の作業中には競合が発生することなく、また優れたブランチ戦略(並行作業を行うために、管理している資材を枝分かれさせる手法)を採用でき、効率よくソースコードの管理が行えるようになりました。例えば、GithubやGitlabなどのソリューションを活用しPull-Request/Marge-Request(プルリクエスト/マージリクエスト)と呼ばれる機能を利用することで、ソースコードの修正された箇所の前後差分をチェックし、修正された資材を効率よく取り込むことができます。

近年、こうした効率のよい管理の仕組みを、ソースコードだけではなく設計書などのドキュメントにも適用する取り組みが、一部の組織や企業で進んでいます。

図1:プルリクエストを用いたドキュメントの修正前後の確認イメージ

図1:プルリクエストを用いたドキュメントの修正前後の確認イメージ

(※1) 2018年に実施されたソフトウェアのバージョン管理ツールに関する調査

https://insights.stackoverflow.com/survey/2018

2. プレインテキストの威力

多くの開発現場では、設計書などのドキュメント作成に、表計算ソフトやワープロソフトなどのオフィス文書作成ツールが用いられます。しかし、これらのツールで作成する成果物はバイナリ形式(※2)であるため、修正前後の差分を人間が確認できるテキストなどの形式で取得することは困難になります。そこで、Git上でドキュメントを管理するために、プレインテキスト形式のファイルを用いることが有効となります。プレインテキスト形式にすることで、ソースコードと同じようにGit上でドキュメント資材を管理し、プルリクエストを通じて修正前後の差分を効率よく確認することができます。

こうしたソリューションは、ソフトウェア開発の名著「達人プログラマー(※3)」でも「プレインテキストの威力」として紹介されています。バイナリ形式のファイルでは、保存されている情報を確認する際には必ずツールが必要となりますが、技術の進歩が高速となった現代では、こうしたツールはすぐに陳腐化してしまう恐れがあります。一方、プレインテキスト形式ではデータの内容は人間が理解できる内容そのもので保存されているため多くの技術・ツールで情報を読み取り・加工・分析することができます。

また、プレインテキスト形式であっても、構造的なドキュメントを作成することができます。いま皆さんが閲覧されているWebサイトもhtml形式ですが、これもプレインテキスト形式の1つです。ドキュメントを作成する際によく用いられるプレインテキスト形式の関連技術として、markdownやasciiDocが挙げられます。これらの技術を用いることで、プレインテキスト形式でも箇条書きや文字装飾、表の作成など、ドキュメントを執筆する上で必要となる構造化はおおよそ実現することができます。

図2:markdownで作成されたドキュメントのサンプルとプレビューイメージ

図2:markdownで作成されたドキュメントのサンプルとプレビューイメージ

ドキュメントの作成には文字だけではなく、フロー図や構成図など様々な図を必要とする場合があります。そうした場合にはplantUML(※4)やmermaid.js(※5)といった技術を活用することができます。これらの技術を用いることで、プレインテキスト形式でもソフトウェア開発に必要な一通りの図を執筆することができます。

図3:plantUMLで作成されたシーケンス図のサンプルとプレビューイメージ

図3:plantUMLで作成されたシーケンス図のサンプルとプレビューイメージ

(※2) バイナリ形式

特定のアプリケーションの定義に従って0と1の2進数で保存されたデータ。テキスト形式は文字コードという予め定められた標準で保存されている点で異なる。

(※3) 達人プログラマー

新装版 達人プログラマー 職人から名匠への道
Andrew Hunt、David Thomas、村上雅章(訳)オーム社 2016

(※4) plantUML

https://plantuml.com/ja/

3. NTTデータにおける活用

NTTデータでは、こうした技術を活用するためのノウハウや、設計書などのドキュメントひな形を社内に展開し、様々なプロジェクトで活用しています。一部のプロジェクトでは、設計書などのドキュメント執筆やレビューに関するコストが大きく削減されました。一見すると、plantUMLなどの活用に学習コストがかかりそうに思えるでしょう。ただ、使用してみればそれほど難しい技術ではないことがわかるはずです。そのため、まずは技術に触れてみることをお勧めします。また、markdownやplantUMLの活用をサポートする多くのツールが存在しています。これらを活用することで、納品・製本のためのドキュメントのpdf化、html化や、全文検索などが可能です。プレインテキスト形式である強みを生かすことで、今後も多くの分野で活用が進むことが予測されます。

更に、昨今のテレワークによる分散開発においては、Gitを活用したプルリクエストによる非同期かつオンラインでのレビューは特に効果的で、ドキュメントのレビューなどによるテレビ会議の時間が削減されました。これらの成果については、先日開催されたソフトウェアテストシンポジウム2021Tokyoで発表を行い、ベストスピーカー賞を獲得しています(※6)

NTTデータでは、こうした技術を活用し、より迅速なお客様のビジネス変革に引き続き貢献していきます。

(※6) JaSST'21 Tokyo レポート

http://www.jasst.jp/symposium/jasst21tokyo/report.html

- NTTデータは、「これから」を描き、その実現に向け進み続けます -
お問い合わせ