はじめに
この記事は東京大学工学部応用物理学系2学科(物工/計数) Advent Calendar 2022 の15日目の記事です。物理工学科・計数工学科の学生が各々の関心事を記事にしています。
僕はインターンでフロントエンドエンジニアをやっているので、この記事ではその観点から優れたレポートの体裁について考えます。あんまり学術的ではないので、学術的なものを期待していた方はごめんなさい。また、他の人のレポートとかほぼ見ないので個人の感覚が多分に含まれることはご了承ください。
実験レポート、読みづらくない？
人生で1度ぐらいは書いたことがあるであろう実験レポート、よくよく考えるとかなり読みづらくないですか？大体の場合、実験レポートは
1. 目的・背景
2. 方法
3. 結果
4. 考察
5. 結論
みたいな構成をしてるわけです。これはまあいいですよね。基本的な構成です。問題はさらにこれがいくつかの小実験の集まりだった場合です。この時、より細分化されて
1. 目的・背景
2. 方法
2.1 実験1の方法
2.2 実験2の方法
2.3 実験3の方法
3. 結果
3.1 実験1の結果
3.2 実験2の結果
3.3 実験3の結果
4. 考察
4.1 実験1の考察
4.2 実験2の考察
4.3 実験3の考察
5. 結論
みたいな構成になることがほとんどかと思います[要出典]。1つ目の基本形を遵守した形です。
これでは読んでいるところが実験1→実験2→実験3→実験1→…と次々と移り変わって非常に混乱しますよね。さらに小実験の数が増えると、これが3つではなくより多くなってしまいます。
これ、読みにくくないですか？？？
何が悪いのか
今の実験レポートの構成の何が悪いのかというと、小実験ごとにまとまっていないため、本来読みたい順と違う順に並んでしまっていることです。実験1だけを追いたかった場合には、
1を読む→2.1を読む→3.1を見つける→読む→4.1を見つける→読む→5を読む
という流れになります。この「見つける」というステップに明らかに無駄があります。飛ばす必要がないのは全ての実験をまとめて読む場合(つまり、上から順に読んでいく場合)のみですが、これに関しても次々に読んでいる実験が変わってしまうことから読みやすいとは言えないでしょう。
目次をつけるという方法も考えられなくはないですが、今回は構成を見直すことでこれの解決を図ります。
ところで、パッケージングにおいては
ここで、プログラミングにおける設計のアンチパターンの1つである技術駆動パッケージングを見てみましょう。技術駆動パッケージングとは、特にDDD(ドメイン駆動設計)の文脈で使われる単語ではありますが、フロントエンドに適用すると例えば
├ components/
│ └ Hoge.tsx
├ providers/
│ └ HogeProvider.tsx
├ contexts/
│ └ HogeContext.ts
└ hooks/
└ useHoge.ts
みたいな感じになります[1]。ざっくり言うと、ある概念があった時に、表示を司る部分、論理を司る部分みたいに分けられています。
これの何が悪いのか？
この設計の問題点は主に凝集度の低さにあります。凝集度とは、ソフトウェアにおける関数やファイルのまとめ方の指針のようなもので、高ければ高いほど良いとされています。関数に対して適用されることが多い考え方ですがディレクトリ構成においても同じようなことが言えるでしょう。具体的には、凝集度が低い順に
- 偶発的凝集(最悪)
- 論理的凝集
- 時間的凝集
- 手順的凝集
- 通信的凝集
- 逐次的凝集
- 機能的凝集(最善)
の7つに分けられています[2]。細かい部分は省略しますが、この時技術駆動パッケージングは2の「論理的凝集」に該当します。つまり、適当に集まっているよりはましだけど見やすくはないよねみたいな感じです。
凝集度が低いコードを書くと、例えばある処理に関連するファイルを見たかった場合にどこからどう探していけばいいのかが分からないなどといった問題が起こります。
設計でのベストプラクティスは？
ベストプラクティスとしては概念ごと(機能ごと)に分けてしまう方法が知られています。1つの例としては、最近リリースされたNext.js(JavaScriptを用いたアプリケーションのフレームワーク)の13.0.0にベータ版として追加されたディレクトリ構成が挙げられます[3]。
├ app/
│ └ dashboard/
│ ├ page.tsx
│ ├ Navbar.tsx
│ └ Navbar.stories.tsx
ここではdashboardというページを作ろうとしたときに、従来であれば/pagesの配下にdashboard.tsxを置いて/componentsの配下にNavbarなどの構成要素をおいていたところを全てdashboardの下に配置する形にしています。
これは凝集度の観点で見ると7の「機能的凝集」にあたると言えるでしょう。つまり凝集度の観点で見ると最善ということになります。
インターン先でも徐々にではありますがこの方針を取り入れています。
これを実験レポートにも適用してみる
改めて実験レポートを見てみると、
1. 目的・背景
2. 方法
2.1 実験1の方法
2.2 実験2の方法
2.3 実験3の方法
3. 結果
3.1 実験1の結果
3.2 実験2の結果
3.3 実験3の結果
4. 考察
4.1 実験1の考察
4.2 実験2の考察
4.3 実験3の考察
5. 結論
これってかなり技術駆動パッケージングと近いものを感じませんか？違う実験が含まれているのに「方法」だからという理由で同じ章にまとめているのはまさに論理的凝集であり、設計におけるアンチパターンを踏み抜いているということになります。
そこで、設計におけるベストプラクティスを踏まえてこれを変えてみると、当然
1. 目的・背景
2. 実験1
2.1 実験1の方法
2.2 実験1の結果
2.3 実験1の考察
3. 実験2
3.1 実験2の方法
3.2 実験2の結果
3.3 実験2の考察
2. 実験3
2.1 実験3の方法
2.2 実験3の結果
2.3 実験3の考察
5. 結論
となるでしょう。多くの場合目的や背景、結論は全ての小実験に対して共通なものであると考えられるので、ここは独立させて、残りの部分に関しては小実験ごとにまとめるという形を取りました。これなら前から順に読んで行っても各小実験でどういう方法をとってどういう結果が得られ、どういう考察をしたのかが分かりやすいですね。
終わりに
ここまでより良い実験レポートの書き方を考えてきましたが、よく考えたら僕はもう実験レポートを書く機会はなさそうです。従ってここに書いた方法を実践する機会もありません。
実験レポートを書く機会がある方で、これを読んで「良さそう！」と思った方がいればぜひ実践してみていただきたいです。
明日はmisawa君が何か書くかもしれないらしいです。
参考
[1]
[2]
[3]