読者です 読者をやめる 読者になる 読者になる

ドキュメントからコードへ

最近「ドキュメントからコードへ」というのをキーワードに考えています。 その辺に関してつらつらと書いてみました。例のごとく英語で書いた資料より日本語の方が詳しいよ><

「ドキュメントからコードへ」って?

例えばいくつかの種類のドキュメントは下記のようにコードに置き換えることが出来ます。

詳細設計書、テスト仕様書 => 自動テスト

サーバの構成定義書 => サーバテストツール

  • serverspec

インストールマニュアル => プロビジョニングツール系

  • chef/puppet

運用手順書 => デプロイツール, JOB管理ツール, CI ツール

  • Capystrano
  • Fabric
  • Jenkins

他にも要件定義や基本設計をAlloy等で作るのもこの範疇に入るかもしれないです。 ドキュメントを自動ツール系のスクリプト定義に置き換えることが「ドキュメントからコード」となります

そもそもなんで必要?

さて、そもそもなにがうれしいんでしょうか? まず思いつくのはコスト削減。 自動化をすることで手作業でやっていたことがボタンひとつでできるようになります。 これはとてもわかり易いですね。では、本当にそれだけが価値でしょうか?

「ドキュメントからコードへ」に移行することで真に得られるもの、それは作業コストの削減ではなく信頼性です。

ここで言う信頼性は大きく分けて下記の3つです。

  • プロダクトの信頼性
  • オペレーションの信頼性
  • ドキュメントの信頼性

プロダクトの信頼性とはシステムのコードの信頼性です。 自動テストツールを入れることで、今まで目視で確認していた様々な項目を簡単に再実行することが出来ます。 これはリグレッションテストをするにあたって強力な武器です。リグレッションテストはデグレや修正の影響を把握するための基本的な方法です。 これによって、コードの品質が保てるというのは分かりやすいかと思います。

プロダクトだけではなく、オペレーションの信頼性もコード化で担保出来ます。 日常の些細な業務から、本番へのデプロイを始め、システム運用にはオペレーションがかかせません。 しかし、それを実施するのが人間であるかぎりミスを犯します。それは確率的な話なので、頻繁にやる作業ほどミスをする可能性が高いといえるでしょう。 一方、プログラムは間違えません。プログラムは書いたとおりには動くので、間違ってなければ正しく動きますし、修正すれば同じ失敗もしません。 これはプロダクトの品質にかなり大きな影響を与えます。

個人的にはもう一点重要な要素としてドキュメントの信頼性向上があります。無論ここで言ってるドキュメントとはコードです。

ドキュメントは多くの場合間違っています。理由は様々です。ドキュメントを作った時点と変わった修正が反映していない。元のドキュメントにミスがある。そもそもドキュメントを見て作っていない。 ドキュメントは容易に壊れます。ドキュメント管理が脆弱な組織では、ドキュメントを見ても結局信用ができないのでコードも見るということはよく有ります。

最後に信用できるのはコードだけ、です。その信頼性の差が何でしょうか? それは実際に動いて使われていることです。 もし、間違えていれば動かない。あるいは要件レベルでバグっていたとしても今動いているものは書いてあるとおりだ、ということが論理的に保証されます。 これは運用をするにあたって大きな安心感を与えてくれます。この1点のためだけでも、仮にドキュメントより作成コストがかかってもコードに落とすべきだと考えています。

まとめ

TDDやBDD, DevOpsで言われるインフラのコード化, Jenkinsなどによるオペレーションの自動化、様々な手法がありますが、作業手順書を無くし自動化することは単なる作業のコスト削減ではありません。 プロダクトの信頼性、オペレーションの信頼性、そしてそれらを支援するドキュメントの信頼性。これらを現実的なコストで実現できるようになります。 つまり、ここで削減してるコストは既存の作業コストではなく、今まで高くて支払えていなかった98%の信頼性を99%にするためのコストです。

作業コストの削減だと割に合わないと思ってた人がもしいましたら、信頼性向上のためという考え方でぜひ実施してみましょう!

それでは、Happy Hacking!