jfluteの日記 このページをアンテナに追加

2017-06-28

コードにコメント書くのにDBにコメント書かないの?

|

※主にサービス開発における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

f:id:jflute:20170530181402j:image

kurokuro 2018/07/02 18:46 いつも楽しくdbfluteをエンジョイしています。

DBのコメントで似たような名前で、間違えやすいものに注意書きをすると後々楽になりました。

REGULAR_PRICE
PURCHASE_PRICE

これだけだと、どっちが定価で、どっちが購入価格か一瞬では判断できません。初心者の私では尚更でした。

仮に粗利の計算をするときに、間違えていたら・・・

なので
REGULAR_PRICE 「定価 販売価格ではないので注意!」
PURCHASE_PRICE 「購入価格 定価に利益やポイントなどを付けて、最終的に購入された金額」

など、注意書きをすると一目で分かって便利でした。

jflutejflute 2018/07/05 15:46 kuroさん、ありがとうございます!
なるほど、"注意書き" って表現良いですね。わかりやすい!
「注意点を書こう!」って使わせて頂きますね(^^

トラックバック - http://d.hatena.ne.jp/jflute/20170628/letsdbcomment