チーム開発で活きる調査メモのすすめ
はじめに
自分が知らない何かを調べる時、どの様に調べていますか？
ソフトウェア開発では、自分やチームが有している知識で解決できる問題もあれば、現状の知識だけでは解決できない問題も多くあると思います。
その様なシーンで行うことは、問題を解決するために必要な知識や手法を調べることだと思います。
せっかく時間をかけて調べたのなら、その過程を記録しチームに共有できると良いなと思っているので、この記事では調査内容をメモする際の観点を文字にしてみようと思います。
調査メモの観点
前提
今回は例として以下の問題（課題）を解決するために調査をし、解決するための実装をする過程をメモとしてまとめていきます。
調査と解決を同時に進めたいことが多いと思うのでこの様な前提としています。
- Cypress のテストレポートを生成し CI でクラウドストレージに保存したい
- monorepo 構成のリポジトリになっており、CI は共通の workflow を利用している
- すでに他のパッケージでは実装されている（はず）
調査をする目的を文字にする
調査に熱中すると、本来の目的から逸脱して調べてしまうことが（私は）よくあります。なのでまず最初に目的を書いておきます。
- Cypress のテストレポートを生成し CI でクラウドストレージに保存する
事実をそのまま箇条書きで書く
文章として成り立たせるために労力を使うのがもったいないので、箇条書きで書くことを強くおすすめしたいです。
箇条書きは意識せずとも簡潔に書けるので、後に誰かがメモを読んだ時にも理解が容易だと思っています。
この時、箇条書きにした順番を下手に入れ換えない方が好ましいと思っています。実際の調査順が上から下に向かって羅列されている方が後に見返した時に思い出しやすいです。
また、自分にとって当たり前だろうと思うことでも文字に起こすことが重要です。調査の序盤はとにかく事実を明らかにすることに努めます。
- Cypress のテストレポートを生成し CI でクラウドストレージに保存する
+ - 他のパッケージは cypress-mochawesome-reporter を使ってテストのレポートを生成している
+ - 同じ形式が好ましいと思うので他のパッケージと同様の設定をした
+ - `github/workflows/foo.yaml` の job `prepare artifact` が発火点
+ - そこで `bar.js` が実行されている
+ - `apps/foo/cypress/integration-test/**` を `root/artifacts/integration-test/**` にコピーしている
+ - `bar.js` に今回の対象パッケージの設定を追記した
仮説と検証を 1 セットで行う
ある程度事実が明らかになり、必要であろう実装をしてもなぜか動かない.. ということが（私は）よくあります。
その様なシーンに遭遇したなら、なぜ動いていないかの仮説をたてます。
- Cypress のテストレポートを生成し CI でクラウドストレージに保存する
~~ 省略 ~~
- `bar.js` に今回の対象パッケージの設定を追記した
+ - しかし CI を実行しても対象のパッケージがアップロードされていないっぽい
+ - 手元で `node bar.js` 実行してみる
+ - `/artifacts` ディレクトリが作成されたけど、そもそも `integration-test` の中身がない
+ - 他のパッケージの Cypress のテストレポートもコピーされていない
+ - Cypress(e2e) 以外の unit test のレポートや storybook は意図したようにコピーされている
+ - この間 Cypress のバージョンあげたのが関係する？
仮説を検証します。
- Cypress のテストレポートを生成し CI でクラウドストレージに保存する
~~ 省略 ~~
- この間 Cypress のバージョンあげたのが関係する？
+ - Cypress を 9 系から 10 系にあげていた
+ - `cypress.json` がサポートされなくなって `cypress.config.ts` に置き換わっていた
+ - `cypress.config.ts` に必要そうな記述を追記した
+ - 再度手元で `node bar.js` 実行するとコピーされた
+ - CI 実行してテストレポートがアップされた
この時、自分がたてた仮説が間違っていたとしても消さずに検証結果を書くことが重要であろうと思います。間違っていても調査した内容がメモされていれば再度同じような検証することを防げます。
間違っていたなら、再度次の仮説を立てて検証を繰り返します。
まとめをする
調査が完了したら原因や結局何をしたかを簡単にまとめておくと尚良いかと思います。
真に調査の目的を達成できているか振り返る機会になります。
完成イメージ
調査メモのなにが嬉しいのか
調査を引き継げる
チームによってはタスクを引き継ぐスタイルをとっていないかもしれませんが、必ずしもチームのタスクを個人が完結させる必要はないので、行き詰まったらパスしたりペアプロに切り替えたりすることもよくあると思います。
その際に、調査メモを残しているとすごく役にたちます。
これがメモを残す最高のメリットといってもよいと思います。
自分が何を思って、何を調べて、どのように実装したのかを説明するのは（それが難しい問題であればあるほど）難しいと思っているからです。
効果的に調査ができる
単純に自分が何を調べたか振り返ることができるのもメリットですが、特に仮説と検証を文字に起こすことで脳みそを効果的に切り替えて調査することができる点が嬉しいです。
自分が今仮説を考えているのか、検証をしているのかが明確になっているのは想像以上に効果があると思います。明確になっていない状態だと（例によって私は）何度も同じようなことを考えたり、よく分からないコードを書いたりしてしまいます。
これは例えるなら、TDD のテストを書く時（仮説）と、テストを通すための実装をする時（検証）のイメージに近い気がします。
お気持ちが安定する
調査のメモが一応アウトプットとなりチームに共有することができるので、チームから見て「1 日調査したのに何も分からんかった」となりません。
「分からんかった」と共有されるよりも、調査メモを共有してくれる人間の方が好まれるのは間違いないです。
ナレッジ共有になる
どの様に調査をしてどの様に解決したのかを知ることができるので、チームメンバーはコードの差分以上の知識を得ることができます。
（この記事を書いていて思ったけど Zenn の Scraps の簡易版っぽいな）
習熟度の高いメンバーがコレをやってくれるとかなり嬉しいですよね。
将来同じような問題が発生した時に役立つ
まあ適切にドキュメント化をするのが良いのは間違いないですが、難しいことも多いので、作業メモを GitHub の Issue のコメントにペタッと貼っておくだけでも役に立つ可能性が高いですよね。
さいごに
最後まで読んでいただきありがとうございました。わりと自己啓発？っぽい内容になってしまいましたが、思うところがあればコメントいただけると嬉しいです。
Discussion