要約：再考 設計ドキュメントの課題 -雑誌『Software Design 2024年10月号』
記事の概要
この記事は
雑誌『Software Design 2024年10月号』
第1特集 再考 設計ドキュメントの課題 二重管理しない，陳腐化させない
の要約になります。
設計ドキュメントは、ITエンジニアにとって悩ましい問題です。情報共有に必要ですが、コードとの同期が難しく、保守が負担になります。本特集では、様々な開発現場におけるドキュメントの扱い方を紹介しています。
チームによる考え方の違い
大規模な開発体制を取る場合、それをリードするアーキテクトは非常に優秀なことが多いです。彼ら彼女らは設計ドキュメントからソースコードを自動生成するなどのしくみを整え品質と生産性向上を目指します。
少人数の開発では、難解になりやすい自動生成などのしくみや、独自仕様になりがちな設計ドキュメントを避け、より少ない設計ドキュメントで開発を行うこともあり得ます。
設計ドキュメントの課題
ソースコードとの同期が取れず、陳腐化しやすい問題があります。
「ビジネス的に最優先での対応が必須で、設計ドキュメントはあとで直す」は大抵の場合、守られません。全員が高い意識を持たなければ保てないしくみは誤っています。腐る余地があるものは必ず誰かが腐らせます。
解決策
- 設計ドキュメントにも保守コストがかかることを理解し、できる限り余計なものを作成しない
- 作成フローを一方通行にすることで、ソースコードと設計ドキュメントのダブルメンテナンスを避ける
- 設計ドキュメントとソースコードの整合性を取るため、レビューや静的解析のチェックで同期を取る
なお、2.の方法には次の方法があります：
- ソースコードから設計ドキュメントを自動生成する
- 設計ドキュメントからソースコードを自動生成する
設計ドキュメントのGit管理のすすめ
Markdownベースのテキストファイルでドキュメントを作成し、Gitで管理することを推奨しています。これにより、Pull Requestベースのレビュー、履歴管理、開発ツールの統一などが可能になります。
ADRの活用
開発の背景や決定事項を記録するためのツールとしてADR(Architecture Decision Records)が紹介されています。背景の不明確さといった問題の解決に役立ちます。
なお、ADRは、2022年にはアーリーアダプターであったのが、2023年にはアーリーメジャーに移行しています。このことから、近年注目されている技術といえます。
設計書なしでも各人が疎結合で開発できるために
できるだけ設計ドキュメントを書かない(株)カカクコム社と(株)ソニックガーデン社の例が紹介されています。
- 単一責任原則によりアプリケーション構造をシンプルに保つなどの開発ルールを定める
- ドキュメントではなく、アプリケーション部品の標準化を行う
- 全開発者(エンジニア)がコードを読み書きできる。「仕様書は書けますがコードは書けません」というエンジニアには無理
- きれいなコード作成、コードレビュー、テストコード作成が重要
- 完全にドキュメントをなくすわけではなく、README、画面設計書、作業手順書などは必要に応じて作成する
OSS開発のドキュメント事情
OSS開発プロジェクトにはヒントがたくさん詰まっています。PostgreSQL、Apache Kafka、OpenStack、OpenJDK、の例を挙げ、OSSプロジェクトでのドキュメント管理方法を紹介しています。
企業内のプロジェクトとは異なる考え方や方法だとしても、必要となる設計思想や影響などをさまざまな方法で記載して残しています。とくに、多くの人が関わり、長く使われているソフトウェアでは、その傾向が強いようです。
OSS開発の現場では、プロジェクトの進め方という観点でも多くの人の英知が反映されています。多くのプロジェクトがオープンな形で進めていますので、みなさんのプロジェクトでも活かせるヒントがたくさんあるはずです。
まとめ
今回の特集を読み、多くの会社でも仕様決定の背景が分からない、仕様書やドキュメントの陳腐化(メンテナンスが漏れている、もしくはされていない)が問題視されているのだと感じました。
特にADRの導入は他の書籍でも出てきましたが、有効な手法だと感じ、社内でも提案していますが、なかなか採用にいたらず、歯がゆい思いをしているところだったりします。
Discussion