E-R図を見ると大体そのサービスがどういうものなのか分かる。という話があるが、データというものはコード以上に寿命が長かったり、結局コードはデータを元に加工して何やかんやしているだけなのでデータを見ればサービスが分かるというのは必然的だ。

しかし、E-R図を見ただけで事細かな実装が分かるわけではない。となれば実際のコードを駆けずり回って読んで行き、断片的な情報から少しずつ読み取っていく必要がある。
これは相当に大変な作業だ。
特にフレームワークを使った開発では暗黙の了解的な部分が多かったり、簡単に分割できるためスッキリしすぎて逆によくわからないといったケースは存在する。

長期間の開発において保守の問題は常に存在する。
それをどう解決していくかによって、プロジェクトの成功や今後の利益、どれだけ続けられるのかといった事が大きく左右される。
今回はそれらの解決策を、MVCフレームワーク、特にRailsを例に出して紹介して行きたい。

初めて関わったサービスを理解するために

新しく既に開発中の案件にエンジニアとして配属された時、コードのどこから見るだろうか？
大体の場合、SchemaかModelだ。
何故ならどんなテーブルが存在し、どうデータを管理しているのか分かるだけでサービスの概要が掴めるから。
しかし今ある全てのSchemaやModelを見ていくわけにもいかない。大体の部分だけ流し見して雰囲気をつかのが最初にやるべき事だと思う。

ならどっちを見るか？

Modelだと思う。
特にRailsのSchemaは後からどんどん変更され、最初のSchemaとは大きくデータ構造が変更されている場合があり、マイグレーションファイルのみでの保存のため非常に該当データを探しづらい。
となれば大体Modelを見て概要だけ知りたいと思うだろう。

とは言えども問題がまだある。

1. Model名を見てなんとなくの心構えをする。
2. Modelのリレーションを見てデータのつながりを確認し、もしかしたらその時点でリレーション先のModelも少し見たくなるかもしれない。
3. Modelのメソッドやバリデーション、scopeをなんとなく見ていき、使われ方を掴む。
4. そのModelを使用しているViewやControllerで実際の処理を見て、どのようなデータのつながりで扱われているのかといった詳しい情報を掴む。

まあ、大体の流れはこのようなものだろう。

一番注目して欲しいのは、Modelを軸に見ているという点だ。

Modelを見ると様々な事が分かる。
Model同士のリレーションが分かる。
データの形式が分かる。
データの使われ方が分かる。

ではModelのそれぞれを見ていかないと概要が分からないのではないか？
これらの流れを見てきて一番思うのは、Model毎にまとめられたどういう意味を持つのかコメントとして概要を書いていれば見た瞬間分かるのではないか？という事だ。

いやいや......コードコメントにはWhy notを書くべきだよ
全く持って同意したい。

コメントやドキュメントを保守するコストってすごく高いんだよ？
いやはや、その通りで。

世の中に溢れているModelが一目でどういうものなのか分かるようになってないんだから、そんなの無理に決まってるだろ！！！！！！！！
大体データの存在意義なんて、そう1ヶ月毎にぽんぽん変わったりしないだろ！！
もし変わってるんだったら設計が悪すぎるか、めちゃくちゃ特殊ケースの場合だけだろ！！！

# 台本を管理し、概要や全体の文を保持する
# 行毎の詳細情報はLineが保持している
class Scenario < ActiveRecord::Migration[5.0]

これだけでこのModelが何をしたいのか、存在意義がほとんど分かったようなもの。
分かりにくい部分のデータの流れも一目瞭然。これ以上細かい情報が必要になればModelの中を見たり、ViewやController、Schemaを見に行けばいい話だ。
Lineに行毎の詳細情報を保存していることも分かったので、そちらを見にいくといった流れもあるかもしれない。

まとめ

たった1,2行のコメントをつけるだけで、最初のリーディングがどれだけコストが低いものになるか分かった。
それだけでなく、新機能追加や保守をする時に使われるModelの概要を把握したい時にぱっと見るだけで理解出来るため、作業コストが大幅に削減できる。
しかもここまで大枠の概要が1ヶ月毎で変更されることなどほぼあり得ないので、コメントの保守コストもほぼかからない。
それだけでここまでの利点が得られるのなら、やらない手はない。

補足

運用のためにエンジニア以外にもこの概要を簡単に見れる必要があるという場合であれば、外部ドキュメントにまとめるといった解決策もあるのかもしれない。
その場合少しコストは上がってしまうが、場合による。