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