Why?
※主にサービス開発におけるDB設計を想定しています。
「JavaDoc書きましょう」
「コード上にコメントを書きましょう」
これは、よく言われるし、わりとプログラマーにはだいぶ浸透していることだと思います。
もちろん、「どんなコメントを書くのか？の精査や修練」は必要だし、「コメントに頼りすぎず、コード自体で伝わる表現をしよう」というのも大切な意識です。
なのに、ひとつ不思議なことを思うことが多いです。みんなコードにはコメントたくさん書くのに、なんでDBにはコメント書かないんだろう？と。
DBはしゃべれない？
コードは、コード自体でストーリーを描けます。変数名やメソッド化、クラス構造など、さまざまなところで業務を表現できます。どうしても表現できない「背景」的なところを補足のコメントで書いたり。
DBは、極端な話データの入れ物です。テーブル名、カラム名、リレーションシップ、カーディナリティやなんとか制約などで、ある程度の表現はできるかもしれませんが、コードほどストーリーを表現できません。
なので、コメントが書いてないDBは...
「ただ建物が建っていて、部屋がある。この部屋には何が入る想定なんだろう？名前は付いてるけどそれだけじゃわからない。広さや窓の大きさからすると、たぶん...こういう目的の部屋なのだろうか。でも...こういう用途もあり得るよなぁ」
ほぼこんな状態。コンセントや電気の配線を考えるのは無理。プログラムを書くためには非常に不健康。
質問責めはお好きですか？
jfluteはDB設計の仕事もよくやりました。DBはシステムの中心とも言えます。DB設計者のもとにはプログラマーから質問の嵐。
質問されること自体はとても良いことですが、単純に程度の問題。あまりに基本的なことの質問が多かったり、別の人から同じ質問が来たり、そういうのはもう半分以上は自業自得。
DBコメントがあれば、質問責めは軽減できます。DBコメントのないDBを作って質問責めされて、仕事が進まないーって言ってもしょうがないのです。
ちなみに、テストデータもDBを伝える手段の一つです。DBコメントだけでなく、テストデータもちゃんと最低限のものは揃えましょう。テストデータを見ればわかることも多いので。
コメントを気軽に見れるツールを
もちろん、DBコメントを書いても、プログラマーの目に入らないのでは意味がありません。DBコメントが気軽に見れるような、自然と目に入るような状態にしましょう。(これは仕組みの話です)
jfluteが実際に現場でやっているのは...
DBFluteのSchemaHTML, これはプログラマーは頻繁に見るもので、SchemaHTMLの中にDBコメントが表示しておけば、自然と目に入るだろうということでそうしています。SchemaHTMLのローカルリンクをBookmarkしてもらい、いつでも気軽に見られるようにしてもらっています。(エクセルやERDツールを起動するってなると、やはり足が重いので積極的に見てもらえない)
また、自動生成されたEntityクラスのメソッドのJavaDoc, ここにDBコメントの内容を(自動で)転記しています。IDE上でJavaDocが表示されるときに、DBコメントも一緒に。
工夫はいくらでもできるはずです。
どんなコメントを書けば良い？
それは、こないだのブログの...
// プログラマーに求められるデザイン脳
http://d.hatena.ne.jp/jflute/20170623/desigraming
での「コメントデザイン」のところと同じ。
何が書いてあったら読む人が嬉しいのか？を考えないと良いものは書けない
です。
想像して考えること。
特にサービス開発では、DB作ってる人もプログラマーであることが多い、意識すれば実は想像できるはず。
DBコメントにどんなことを書くのか？ってルールがなくても...
気の利いたコメントを考える
という習慣を。
一方で、なんのコツもないかというとそうでもないので、ちょこっとjfluteが考えたコツをご紹介。これが全てじゃないので、これさえ書いていればOKとは思わないように。ただ、何も書かないくらいだったら、これだけでも書いててもらえればって感じでもあります。
コツ一: レコードの粒度を書く
そのテーブルには、レコードがどんな粒度で入るの？
(業務的な意味合いで)
ある意味でこれ一番知りたいことです。
真っ先に知りたいことです。
ユニーク制約を貼るなりして、制約で表現するべしってのもありますが、貼れないような状況のテーブルもありますし、貼ってあったとしても、そのなかで若干の業務的な制約もあったりするので...「テーブル名から推測しづらい、誤解されやすい」そういうテーブルに関しては「粒度」があると良いです。
そのデータの積み上がる「想定」とも言えますね。
コツ煮: null
まあ、そもそもテーブル設計の工夫で、NotNull制約のないカラムを作らないように...ってのはあるのですが、どうしても作らざるを得なかったのであれば、
どういうときに null になるの？
これがわからないと、プログラム側でどういう制御をすべきかわかりません。「値がある、ない」ってすごい重要なんですよ。
一度 null になったあと二度と値が入らないとか、nullと実値を行き来するかどうか？などのライフサイクルも知りたいところです。
一方で、one-to-one (1:いないかもしれない1) という感じでカーディナリティで "ないもの" を表現したときも、どういうときにないのか？は、いくらERDを見てもわかりませんから、しっかりコメントで書いておきましょう。
コツ産: サンプル値を書く
どんな値が入っているのか想像しづらいカラム、言葉で説明するのは大変なので、それはもう、サンプル値をコメントに載せちゃいましょう。
MEMBER_STATUS_NAME: e.g. 正式会員
REMINDER_QUESTION: e.g. 110符2翻は？
PRODUCT_HANDLE_CODE: e.g. X00-ABC
これはコード上のコメントでもよく使う手です。ある意味で一番わかりやすく、書くのも楽。
"e.g." と付けておくことがポイントです。あくまで「例えである」ということで、実際にその値が入っている必要はなく、「実値が変わったからコメントも変えなきゃ」ってことがないように。古くなったコメントは紛らわしいので。
(その例え値自体が絶対にあり得ないってくらいの変更であれば、もちろん修正は必要ですが)
コツよん♪: 周辺物理に依存しない
コメント書いた後にあれこれ変わって、コメント自体が古いとなるとそれはまたBadです。
DB自体が変わったのであれば別にコメントを直せばいい、直さないほうが悪いという感じですが、DB周辺の物理的な話に依存した内容を書いたりすると、変わったときになかなか追従できません。そういうものはあまり書かないほうがいいし、それ書かないと伝わらないというのであれば、少しぼかして抽象的な表現を心掛けましょう。
伝えたいことは周辺物理ではなく、それによって影響するDB自身のことなので、自然言語の表現でうまく切り出せればと。
コツ呉: RDBで表現できてない業務上のルール
RDBの構造や制約では表現できないもの、これはよほど定型的でなければ絶対に伝わりません。(というか、すべてここに集約されちゃうのかもしれませんが...)
そもそも、そういうイレギュラーなルールは作らないようにしよう、というデザイン工夫は当然ですが、「業務的one-to-one」など多少仕方がないケースもあるので、それはそれでしっかりコメント書いておきましょう。
開始・終了日時なんか、終了日時ってその日時自体を含むのか含まないのか？境界がどうなっているのかってのも、プログラムでの "<=", "<" に影響しますので、一言でも補足があると良いです。
コツ募集
先の通り...
「こういうことを書けばいい」ではなく、「読み手が喜ぶものを想像する」という基本、これを念頭に置きながらも、そのための思考のヒントとしてコツを知るというのも大切です。
これに関しては、コツを募集したいという気持ちもあります。もしよければ、コメントいただけるとうれしいです(^^。(自分は、こんなこと書いてるよーとか)
まあ、よく質問されるものを書く、ってわかりやすいお約束もありますね。
ディベロッパーみんなでコメント書こう
そのテーブルやカラムを作った人が作る瞬間に書きましょう、というのも当然ですが、なかなか完璧にそれをこなすのは難しいでしょう。というのは、その時点ではコメントに書くべきものがまだ想像できてない可能性があるからです。想像するという努力目標はありながらも、100点は不可能です。
なので、そのテーブルやカラムに対峙したディベロッパーが、「こんなコメントあったら嬉しかったなぁ」と思ったときに、そのディベロッパーが自らコメントを修正・追記できたら、DB自体の透明性がどんどん増していくと思います。というか、これがコメントを豊富にしていく鍵だと思っています。
ただ、そのコメントをどこにどう修正・追記したら、スムーズにDBコメントとして反映できるのか？ここは仕組みや運用的なところを考えないといけません。
一つ確立されたやり方として...ERFluteは保存形式がXMLでマージがしやすくできています。ディベロッパーが各機能のチケットブランチで、ermファイルを「コメントだけ修正」してコミット。
いままでは、DB変更ブランチ(alter_dbって名前が多い)だけで、ermファイルを修正してOKというような運用でしたが、少なくともコメントだけの修正であれば、もうそこは気にしなくていいかと思います。
万が一、同じカラムのコメントを二人の人が同時に直したら、もちろんgitでコンフリクトしますが、そのマージ作業は大した話ではないし、レアケースではあるので許容できるレベルかと。(というか、そのくらい活発になれば、もう成功の泉に一方足を突っ込んでると言えます)
...
一方で、ちょっといまとあるツールを作っています。もっとスムーズにみんながDBコメントを書けるようにと、企んでいます。
【追記】
企みました。非常に評判良いです！
=> Decomment (でこめんと) on Intro | DBFlute
