BT

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

寄稿

Topics

地域を選ぶ

InfoQ ホームページ アーティクル 継続的ドキュメンテーション - コード知識共有への新たなアプローチ

継続的ドキュメンテーション - コード知識共有への新たなアプローチ

ブックマーク

キーポイント

  • The current status quo for sharing engineering knowledge within teams is broken. Code documentation requires new methods and tools to improve team efficiency and productivity.
  • Continuous Documentation is a new paradigm for creating and maintaining code documentation that involves incorporating it into the normal development workflow.
  • The principles of Continuous Documentation require that documentation be always up-to-date; be created at the most opportune time; and be tightly coupled with the code.
  • By practicing Continuous Documentation we can get high-quality documentation that actually works for developers, guiding them through the code base, while speeding up development and improving agility.

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

私たちは継続的インテグレーションを実践しています。継続的にテストし、継続的監視しています。そしておそらく、継続的にデプロイしているでしょう。これほど重要な継続性が、なぜ、ドキュメントに関しては成立しないのでしょう?

開発者は、品質の高い、最新のドキュメントを求めます — 使い心地のよいキーボード、ワイドスクリーンモニタ、コーヒー、作業のための静かな環境、といったものを求めるのと同じように。自分自身の書いたものではないコードを構築、確認、変更しなければならない場合、開発者には、コードの機能や背景、根拠などの理解を支援するドキュメントが必要です。ドキュメントがあれば、リバースエンジニアリングをしたり、知っているかもしれない人を探してスレッドやチャネルを探し回ったりして、時間を浪費する必要はなくなります。

しかし、開発者の要求を満たすようなドキュメントは手に入らないのです。なぜでしょう?それは、現在のドキュメント作成のプラクティスが、根本的に機能していないからです。現在の状況は、継続的インテグレーションが導入される前のテストの状況によく似ています。開発者は集中的なスプリントでドキュメントにアプローチしています。多くのものを一気にドキュメント化しているのです。そのため、ドキュメント作成は次第に後手に回るようになり、ついには開発が終了して未完成のまま残されます。このパターンは、開発者が多数のユニットテストを一気に実装するため、数か月後にはその多くがコードと同期できなくなる(その結果、不適合で使い物にならなくなる)ケースと、非常によく似ています。

現在のツールとプラクティスを前提とした場合、高品質なドキュメントを作る作業は、時間と労力が掛かりすぎるのです。勢い、急速に進展するコードとペースを合わせて更新することは、ほぼ不可能になります。ドキュメントが有効であり続けることを保証できないのであれば、そもそも、ドキュメントを作る意義があるのでしょうか?私たちには別のアプローチが必要なのです。それを私は継続的ドキュメンテーション(Continuous Documentation)と呼んでいます。

ですが、なぜ今なのでしょう? ドキュメントの欠如は今に始まった問題ではありません。おそらくはコードそれ自体と同じ位、古くからあった問題のはずです。それは、

  1. コードが複雑化したから、
  2. 開発者がプロジェクトからプロジェクトへ、チームからチームへ、企業から企業へと、かつてないほど頻繁に移動するようになったから、そして
  3. 現在はこの問題を解決できるツールがあるから、です。

継続的ドキュメンテーションの目標

継続的ドキュメンテーションを採用すれば、ドキュメント作成はずっと簡単になります。常に最新化され、必要な時に簡単に見つけられるようになります。ドキュメントを単にすべての開発者が求めるものではなく、投資の対象として価値あるものにします。

継続的ドキュメンテーションは、コードベースとコード固有の知識との隔たりを最適化し、削減するプロセスなのです。継続的ドキュメンテーションは、ドキュメントの自動化インテグレーションというパラダイムを開発パイプラインに適用します。ドキュメントを段階的に構築し、更新することによって、コードベースとの同期性を維持するのです。

ドキュメント作成作業を等分に分散してバックログの蓄積を防ぐだけでなく、内部的な開発ループ速度 — アイデアをコードベースの変更として実際にプッシュするまでの時間を大幅にスピードアップします。

継続的ドキュメンテーションの原則

継続的ドキュメンテーションがドキュメントに実現するもの

  • 常に最新である
  • 最適な時に作成される
  • コードと一致する

常に最新である

ドキュメントを継続的に検証することで、コードの進化と同時に、ドキュメンテーションの現在の状態とコードベースの現在の状態が一致していることを保証します。ドキュメントをコードと同期可能にするためには、既存のドキュメントを、コードの現在の状態に対して継続的かつ自動的にチェックする必要があります。ドキュメントがコードの現状から乖離した場合、更新された状態を反映するように(自動であれ、手作業であれ)ドキュメントを修正しなければなりません。ドキュメントを継続的に検証することによって、開発者はドキュメントを信頼できるようになります。書かれていることが現在も有効かつ適切である、少なくとも有効でない部分が明確に示されている、ということが分かるのです。

この意味で、継続的ドキュメンテーションは継続的インテグレーションによく似ています — ドキュメントが常に正しいということは、すべてのテストをパスすることと同じだからです。これをコミット、プッシュ、マージ等のバージョン管理メカニズム毎に実行するのです。そうでなければ、ドキュメントを最新の正確なものに保つのは至難の業です。手作業による修正を定期的に、繰り返し行わなくてはなりません。

注意しなければならないのは、ドキュメントが現在のコードベースの状態と一致しないことを単に警告するだけのシステムは、それ自体が負担になるため、開発者に受け入れられる可能性が低い、ということです。優れた継続的ドキュメンテーションプラットフォームは、ドキュメントの自動更新が、少なくともほとんどの場合において可能である、ということを目指す必要があります。

最適な時に作成される

継続的ドキュメンテーションがなければ、ドキュメントが作られる機会はほとんどありません。新規採用メンバの参加などで必要に迫られて、というのはよく聞く話ですが、その時にはすでに手遅れなのが普通で、一部の人だけが知っていればよいようなコードの重要な部分は省かれてしまうことになります。

継続的にドキュメントを作るということは、後日ではなく、適切な時点でドキュメントを書くということです。例えば、大規模な機能が完成した時や、重大なバグが解決した時などは、他のコード開発担当者もその内容を知っておくか、理解しておく必要があります。この時点であれば、開発者の記憶も鮮明で明確ですから、ドキュメントを作るのもずっと容易なのです。

コードと一致する

コードと結合したドキュメントとは、コードの一部を明示的に参照するドキュメントである、という意味です。すなわち、コードの単なる説明ではなく、コードの一部を含むか、あるいは指し示すことで、どのソースファイルの何行目を説明しているか明確になっている、ということです。これらはコードのスニペットであったり、関数や変数、あるいはコードの他の部分の名称であったりします。

コード内のコメント("インライン・ドキュメンテーション"とも呼ばれます)は、コードと結合したドキュメントのひとつの形式で、参照するコードが変更された時に更新されます。一方で、コメントはその近辺のコード行について説明することしかできないので、非常に制限されたものになります。理解しやすいコードを書くということも、コードと結合したドキュメントとして述べることは可能ですが、それによって説明できることには限界があります。コードの部分間のやり取りやプロセス、データフローといった側面は、コードコメントやコードの理解しやすさで明確化することはできないのです。継続的ドキュメンテーションツールは、コードコメントでは表現の難しい理論的根拠や実験、その他の得難い知識をコードと結合できるものでなくてはなりません。

アーキテクチャ資料のような高レベルのドキュメントをコードに結合できるのは、それらがコードの部分を具体的かつ明示的に参照する場合に限られます。通常はそうではありません。そういった資料の目的が、コードよりも高いレベルでの説明を提供することだからです。

どうすればよいのか

開発者にとって本当に意味のあるドキュメント — 実際のコードを含むドキュメントを書くことは、高レベルの視点だけではなく、コードベース内で処理がなぜ(why)、どのように(how)行われているのかを、本当の意味で説明することを可能にします。さまざまなファイル、クラス、さらには複数のリポジトリを渡り歩くコードの旅に、読者を誘うことができるのです。このようなドキュメントは、最初にコードを書いた人物から直接説明を受けるのと同じように、コードのウォークスルーを可能にします。実質的にこれは、開発者が頻繁に行うであろう変更プロセスについて、ステップバイステップで説明するマニュアルを提供する、ということになります。

ドキュメントとコードが結合されていて、コードのどの部分がどのドキュメントに対応しているのかが分かれば、そのドキュメントは最新であるという確証を持つことができます。さらには、コードのどの部分がドキュメント化されていて、どの部分がまだなのか、というドキュメントのカバレッジを測ることも可能になるので、新たなドキュメントを作成する時に注力すべき部分が分かります。

ドキュメントの見つけやすさも改善されます。高品質で最新のドキュメントがあったとしても、必要な時に利用できなければ、それは宝の持ち腐れです。知識の蓄積とは、知識にアクセス可能である、ということなのです。コードと強く結合したドキュメントを用意することによって、関連するドキュメントをジャストインタイムに見つけることができるようになります。例えば、あるファイル内のコードを読んでいて、そのコードについて説明した関連ドキュメントを参照する、ということが可能になります。

要約

詳細を知らないコードを短い時間で理解するためには、実用的で高品質な、最新のドキュメントが必要です。このようなドキュメントは開発速度を向上すると同時に、開発者が短期間でタスクをシフトできるようにすることによって、開発チームのアジリティを実現します。

しかしながら、高品質のドキュメントを作成し、最新に維持するプロセスは、時間や労力の面において高価であるため、それを必要とする人たちにとって、必ずしも現実的なものではないのが実情です。ドキュメントの作成と利用の方法を変えなくてはなりません。そのためには、新たなアイデアと並行してコードに結合したドキュメントを作成し、常に最新状態を維持するという、継続的ドキュメンテーションの原則に従う必要があるのです。

このアプローチが皆さんのチーム、あるいは開発者全般にとって、知識を共有する方法を再考する手がかりになれば幸いです。コードに関する知識を共有する方法を変えなくてはなりません。ここで説明した原則に従って、まずはチームが、正しい方向に小さな一歩を踏み出すことから始めてください。継続的ドキュメンテーションの適用範囲は広いので、想像も付かないような方法で開発チーム内のアジリティを実現することができるでしょう。適切なツールがあれば、このアプローチに従う上での障害は何もないはずです。開発者には継続的ドキュメンテーションが必要なのです。

著者について

Omer Rosenbaum氏は、チームとコードを同期する企業であるSwimm社の共同創業者兼CTOです。。さらに氏は、Check Point Security Academyを創立し、技術キャリアの開発を目的として才能のある専門家を訓練する教育組織のITCでは、Cyber Security Leadを務めていました。

この記事に星をつける

おすすめ度
スタイル

こんにちは

コメントするには InfoQアカウントの登録 または が必要です。InfoQ に登録するとさまざまなことができます。

アカウント登録をしてInfoQをお楽しみください。

HTML: a,b,br,blockquote,i,li,pre,u,ul,p

コミュニティコメント

HTML: a,b,br,blockquote,i,li,pre,u,ul,p

HTML: a,b,br,blockquote,i,li,pre,u,ul,p

BT