アーキテクチャの検討を記録するADR(Architectural Decision Records)の方式で、自身がADRを採用するか検討した。

  • ステータス: 承認
  • 決定者: @niku
  • 日付: 2020-05-19

文脈と問題点の説明

ソフトウェア開発中に、あるアーキテクチャを採用した理由を知りたいことがある。

幸運にもそのアーキテクチャを採用した開発者にインタビュー可能で、また開発者の記憶が定かであれば、当時どのような状況・どのような選択肢が用意されている中から選択したかを明らかにできる。 しかしそうではなかった場合、過去に採用したアーキテクチャを盲目的に受けいれたり、完全に無視するといった不健全な意思決定を強いられることになる。

そこで、決定の粒度が大きくかつプロダクトの品質に大きく影響を与えるアーキテクチャ上の変更の「なぜ」を記録し、時間が経過した後も簡単にアクセスできるよう ADR という手法を用いる。

決定要因

ADR を書いた場合、ソフトウェアの費用に比べて効果が上まわるか？

  • 私たちが ADR を書くのはどのくらい手間がかかるか？（初期費用）
    • ADR を書かない場合はゼロ
    • （目安として、この ADR は半日くらいかけて書いている）
  • 私たちが ADR を読む意義のあるドキュメントとして維持し続けるのはどのくらい手間がかかるか？（維持費用）
    • 維持費用は低い
    • 承認済あるいは却下になったら、ほとんど変更は入らない
    • ライブラリを用いたコードのように最新版に追随し続けるということも不要
  • 誰かが ADR を読んだらどのくらい役に立つか？（効果）
    • あるアーキテクチャにした理由がわからなければ、それを改善するための調査・制定費用は高くつく
      • アーキテクチャを決めた関係者がいなくなると、当時の状況と決定に至った経緯が失われる
      • アーキテクチャを決めた関係者であっても年月が経つと記憶は失われる
    • ADR はアーキテクチャを決めた後の時間経過が長ければ長いほど存在意義が高まる
      • 時間の経過とともに関係者は入れ替わり、また同じ関係者がいたとしても記憶は失われると仮定する
        • アーキテクチャを決めた直後は関係者の聞きとりも容易、また関係者の記憶も鮮明なため ADR がなくとも補完可能
        • アーキテクチャを決めて時間が経過すると上記の補完が困難になるため ADR の存在意義が高まる

検討した選択肢

  • ADR を書かない
  • ADR を書く

決定内容

以下の理由により選択肢「ADR を書く」を採用する。

  • 一般に製品の寿命が長いものを作る場合は初期費用ではなく維持費用が大きな要因を占める
  • ADR を書いた場合の維持費用は低い
  • ADR を書いた場合の効果は、アーキテクチャ決定からの経過時間に応じて増大する
    • 決定した人間の記憶が薄れるため
    • 決定した人間への聞きとりが配置転換や転職などにより行えなくなるため

今回作ろうとしているソフトウェアの特徴は以下のとおりで、上記の一般論にあてはめると ADR 記述の効果が費用を上まわると想定される。

  • 寿命は 1 年以上の長さが予想されている
    • 初期費用は支配要因ではなくなる
    • 一定時間あたりの維持費用と効果を比較してよい
  • アーキテクチャは今後も進化する
    • アーキテクチャを比較し決定することが多数あるとかなりの確度で予測される

検討したこと

コミットログでは足りないのか

何をどのように変更したかはソースコードの差分を見るとわかる。行儀のよいコミットログがあれば、なぜ変更したかコミット単位での理由がわかる。どちらもソースコードのバージョン管理システムを使っていれば容易に取得できる。

一方で複数のコミットからなる変更をなぜ行ったかを保存し一覧を平易に眺めるという機能はバージョン管理システムには存在しない。フィーチャーブランチをマージするときのコミットログに書くという運用で複数コミットの変更理由を保存することもできるが、一覧を平易に眺めることはできない。

またそもそもコードの変更を伴わない変更、たとえば運用環境の制定や、前提条件の緩和、あるいは検討した結果コードに手を加えないことを決定したものなどはコミットログとして残らない。

上記よりコミットログでは足りないと判断した。

リンク