はじめに

どうもKizukuです．
みなさんハッカソンの参加経験はありますか？
ハッカソンの時にドキュメント整備はしていますか？
チーム開発をする場合はハッカソンであってもドキュメントを書いておくほうが何かと便利だったりします．
そこで，この記事ではハッカソンで使えるドキュメント整備術について書きたいと思います．
今回はADRの回です．
他のドキュメントに関しては，こちらを参照してください

(この記事内で出てくるハッカソンは2,3日程度の短期間のハッカソンのことを指します．1ヶ月以上の長期ハッカソンの場合は，もっとちゃんとしたドキュメントを書きましょう)

対読者

ドキュメントをあまり書いたことがない人
ハッカソン大好きな人
チーム開発好きな人

ADRとは

Architecture Decision Recordの略で，日本語で言うと「アーキテクチャ決定記録」です．
その名の通り，そのアプリケーションにおける，アーキテクチャ(使用技術)についての技術選定の理由を記録するものです．
単に理由だけを記述するのではなく，どのようなコンテキストで決定されたのか，また，その決定によってどうなることが期待されているのかも合わせて記述します．

記述すべき内容

ADRの書き方には，いくつかの流派がありますが，一例を紹介します．

背景

どういう背景で技術選定を行うことになったのかを記述します．
選定の際に重視するポイントもここに書きます．

決定

最終的にどの技術が選ばれたのか結論を書きます．

理由

どういう理由や観点でその技術が決定されたのかを書きます．できるだけ多くの情報を残して，あとから見た人が意思決定の理由を容易に推測できるようにします．
その技術を使うにあたっての懸念点もあれば書いておきます．

代替案

候補になった他の技術を書いておきます．不採用になった理由も簡潔に書いておきます．
私はここに第２候補となったものを明示的に書いておきます．
もし，実際に開発を進めていく上で使用技術を変更せざるを得なくなった時に，役立つかもしれないからです．

影響

この技術を選定するにあたって，他の部分に影響が出る場合や，追加の作業を書きます．
備考欄的なメモ書きもここに書きます．

参考情報

技術選定する上で参考にした記事等のリンクを書いておきます．

執筆日

このADRを書いた日付を残しておきましょう．
後から見た時に参考になります．

Tips

先ほど書いた記述するべき内容をテンプレート化して，自動生成すると楽です．
私は，scaffdogを用いた自動生成をよく使うのでその設定を残しておきます．

.scaffog/ADR.md

---
name: 'ADR'
root: '.'
output: './docs/ADR'
ignore: ['.']
questions:
  number: 'バージョン管理'
  category: '何の技術選定をしたか教えてね'
  fileName: '決定した技術を教えてね'

---

# `{{ inputs.number | rtrim }}_{{ inputs.fileName }}.md`

```markdown
# ADR (Architecture Decision Record) for {{ inputs.fileName }}

## {{ inputs.category }}の技術選定

### 背景

### 決定

### 理由

### 代替案

### 影響

### 参考情報

執筆日：{{ date "YYYY/MM/DD HH:mm" }}

``` (これは一例です)

また，生成時のコマンドもやや複雑になるためMakefileに記述しておくことをお勧めします

Makefile

##### scaffing

ADR_COUNT:=$(shell find docs/ADR -type f | wc -l | tr -d ' ') 
adr:
	npx scaffdog generate ADR --output 'docs/ADR' --answer 'number:${ADR_COUNT}'

make adrを実行することで，{バージョン番号}_{決定した技術}.mdという形式でADRのファイルを生成することができます．
(この例ではdocs/ADRにファイルを生成することを前提としています．)

サンプル

ADR (Architecture Decision Record) for ristretto

Goのインメモリキャッシュの技術選定

背景

セッション情報を保持するインメモリキャッシュの選定を行う．
今回はパフォーマンスを最優先事項として技術選定を行う．

決定

ristrettoを採用する

理由

今回の最優先事項がパフォーマンスであることから，最もパフォーマンスが良いという観点から，ristrettoを採用した．
githubのスター数は他のパッケージと比べると少ないものの，リリース頻度が高く，直近のリリースも比較的近いため，今後も継続して開発が行われることが想定される．
また，watchが多いことから，他のユーザーからの関心も大きいと判断し，ユーザー数(スター数)も今後増加すると考えられる．

代替案

go-cache
- かなりメジャーなパッケージ．代替案の中では最もgithubのスター数が多い
- 最新リリースが6年前であるため，最近はあまりメンテナンスがされていないと考えられるため，採用を見送り
bigcache
- 利用しやすそうなinterfaceとなっているため，開発効率は良さそう
- item全体でTTLを設定できる
- githubのスター数も多く安定して使うことができそうであるため，第２候補とする
golang-lru
- シンプルな機能となっており，扱いやすそう
- シンプルすぎるが故に，カスタマイズが必要となった場合に苦労しそうなので採用を見送り

影響

うまくキャッシュできているかどうか，テストする必要あり
キャッシュに使うメモリ量についても要検討

参考情報

執筆日：2023/12/11 23:16

おわりに

ここまで読んでいただきありがとうございます！
今回紹介したのは，チーム開発における最低限のドキュメントの書き方です．長期間のハッカソンや実際の業務の場合はもっと書くべきことは多くあると思います．
たかがハッカソン，されどハッカソン．
ドキュメントを整備して快適で効率的な開発になるようにしましょう！