DBのメタデータを管理する文化を作る

第31回中国地方DB勉強会の発表資料です。
情報格差を減らす取り組みとして、テーブル・カラムにコメントを追加していきました。それまでの経緯と、実際にコメントを追加するときに使った手法、その効果などを発表します。
スライドの最後に、具体的にどうやったかを書いたブログへのリンクや、途中で紹介したオープンセミナー岡山2020のページへのリンクを載せています。
ご興味のある方は是非ご覧ください。

Transcript

1. DBのメタデータを管理する 文化を作る 2021-04-02 第31回中国地方DB勉強会 株式会社リゾーム 尾古 豊明(@patorash)
2. 目次 • 自己紹介 • 会社紹介 • 担当製品紹介 • 元々あった課題について • 新たな課題について • 情報格差を解消するためにやっていること • なぜカラムにコメントをつけるのか？ • データベースのカラムにコメントを付けるためにやったこと • まとめ
3. 自己紹介 名前：尾古 豊明（おこ とよあき） twitter： @patorash 所属：株式会社リゾーム システム企画・開発部 役職：専門職 仕事内容： ショッピングセンターに関連するサービス開発 Ruby on Railsで自社サービスの開発・運用（8年目） 近況：歯の親知らずを抜いたが痛みが思ったより長く続いて苦しんでいる。 20代のうちに抜いとくほうが治りも早くて良いらしい。 ちなみに今月もう一本抜くので怖い。
4. 会社紹介 株式会社リゾーム • 岡山県岡山市にある会社。創立30年を迎えた。 • ショッピングセンター向けのシステム開発・コンサル等 • 基本的に自社開発。MS系とRails系の2チームがある。 • Rails系のチームでは、AWS・Heroku・CircleCI・Mackerel等を使用。
5. 担当製品の紹介(SC GATE) 日本全国のショッピングセンターにある ショップの出退店をデータベース化した Webサービスを開発。 Rails3系の頃から開発していて、 現在はRails6.0系の最新。 昨年、脱CoffeeScript、Webpacker導入など、 一応ギリギリでモダンなところを 取り入れている。
6. 元々あった課題
7. 開発メンバーが増えない
8. 経緯 • 立ち上げの時に私のみアサイン。 • 他のプロジェクトに比べると手が掛からない構成のため、 ほぼ1人で開発を継続。 • 他のプロジェクトから開発メンバーが追加されることもあったが、 他のプロジェクトが忙しくなると戻る、を繰り返して早8年。 • 昨年9月から新卒入社2年目の後輩がアサイン！ • 今年になってパートナーさんも追加！ • 突如3名体制になったのである！
9. 新たな課題
10. スキルの違いが大きい
11. スキルの違いが大きい • 私はRails歴9年 • 2年目の後輩は1年目は社内研修＋α。アサインされるまで、 本格的な開発経験はなく、機能開発を完全に任せるのは難しい。 （最近になって多少できるようになってきた） • パートナーさんはRuby、Railsは初めてとはいうものの、他言語での開発経験があ るため、飲み込みが早い。しかし、運用のことは任せられない。
12. 当初の考え • 製品の概要や運用フローなどはもうドキュメントにしてある • 仕様に関しては、ざっくりとは説明したけれど、 細かいところは実際に開発しながら把握していくしかなかろう • 結構ドキュメント化はしているから、わからないところがあったら 質問してくるでしょう
13. 実際は任せづらい… • 製品が成熟しているため、割と高度なバックログが多い。 • とはいえ、仕事をしてもらわなくては…と、できそうなバックログを振るも、思ったより 上手くいかない。 • うまくできないけれど、質問も来ない。 質問がきたら「答え教えてください」のようなものが多い。
14. 2冊の本に出会う
17. オープンセミナー岡山2020の話を聞いて （興味のある方は公開動画をご覧ください）
18. スキルの違いが大きい 情報格差が大きい
19. 本を読んだり、OSOの後での考え • 私は長年のドメイン知識の優位性＋経験で開発スピードが速いだけ。 • ドメイン知識が乏しいと、わからないことがわからない。 • 後輩のスキルがなかなか上がらないと感じていたが、スキル以前にドメイン知識が 乏しいせいで躓いてしまっているのではないか？ • ドメイン知識が増えれば自身で課題に気付き、自律的に動けるようになる。 • このままだとドメイン知識のギャップが埋まるには相当な時間がかかる。 つまり、スキル向上もかなり時間がかかると思われる。 • より積極的に暗黙知を形式知に変換していかなければならない。
20. 情報格差を解消するために取り組んでいること • 朝会・夕会をする • バックログから作業チケットを作る際に私が作成しておく • ハマったらすぐテレビ会議してもOKとする • 場合によってはVSCode LiveShareでペアプロする • リファクタリングデーを設ける • ライブラリを管理するファイルにコメントを付ける • データベースのテーブル・カラムにコメントを付ける
21. なぜテーブル・カラムにコメントを付けるのか？ • MVCのモデル層にはビジネスロジックが集まる • モデル層を読み解くには最もドメイン知識が要る • 一見では意味のわからない英語のカラムの存在(ドメイン由来) • (経験の浅い人にとって)謎のテーブルの存在(ライブラリ由来) • (経験の浅い人にとって)謎のカラムの存在(ライブラリ由来) • ここにコメントをつければかなりの量の暗黙知を形式知に変換できる！
22. モチベーションを高めたい • Mackerelでコメントの入っているカラム数を計測する仕組みを作る。 ◦ テーブル＋ビュー数 ◦ カラム数 ◦ コメント数 • 実装については、ブログを読んでください。 （最後のスライドに載せています） • 計測した結果…
23. テーブル数75・カラム数775
24. 形式知に変えられるのは私だけ… でも愚直にやるのは辛い
25. 流石に楽をしたい… • メタプログラミングで国際化(I18n)のデータがある場合はそれをコメントとして入れ るようにして、約70%のコメントを埋めることができた # == Schema Information # # Table name: prefs # # id(都道府県ID) :integer not null, primary key # region_id(地方ID) :integer not null # name(都道府県名) :string(255) not null # # Indexes # # index_prefs_on_name_and_region_id (name,region_id) UNIQUE # class Pref < ApplicationRecord
26. もっと分かりやすくしたい • ActiveRecord::Enumを使っている箇所は、カラムに入っているデータは 実際はただの数字で、その値が何を示すのかがわからない • 再度、メタプログラミングで、コメントにどの値が何を示すのかを入れた • Before • After # status(ステータス) :integer default("accepted"), not null # status(ステータス:{0=>"受付済", 1=>"処理中", 2=>"完了", 3=>"失敗"}) :integer default("accepted"), not null
27. 残り30%を埋めたい • どのテーブルのどのカラムにコメントがないのか？プログラムで調べる。 • プログラムでコメント追加用のコードを生成させた。 • あとは無心にtoのところにコメントを書いていくのみ。 # table_with_columnsは、テーブル名をキーとする Hashオブジェクト table_with_columns.each do |table, columns| columns.each do |column| puts "change_column_comment(:#{table}, :#{column.name}, from: nil, to: '')" end end # => 出力は以下のように …。これをマイグレーションファイルにコピー &ペーストする change_column_comment(:posts, :id, from: nil, to: '') change_column_comment(:posts, :title, from: nil, to: '') change_column_comment(:posts, :content, from: nil, to: '') change_column_comment(:tags, :id, from: nil, to: '') change_column_comment(:tags, :name, from: nil, to: '')
28. コメント付与率90%近くに上昇！
29. テーブル・カラムにコメントを入れた効果をヒアリング • A5SQLでテーブル定義を確認する際に 日本語で表示されてわかりやすい • 知らない単語の意味を調べる手間が なくなった • 単純に英語よりも日本語のほうが 読みやすいし理解しやすい
30. まとめ：文化は作れたのか？ • ここ1か月ちょっとのことなので、文化を作る基礎ができた、と言いたい。 • パートナーさんがテーブル生成時にコメントを付けてくれていた。 • Mackerelで可視化されたことと、既存のコードにコメントが付いているので、コメント を付ける動機付けになった。 • 割れ窓理論のように、コメントのないカラムを放置しないよう、 啓蒙を続けて文化を育んでいきたい。
31. ご清聴ありがとうございました
32. リンク • DBのテーブル数、カラム数、コメント数をMackerelに登録するrake task作った - patorashのブログ • I18nのデータを基にDBのカラムにコメントを追加する - patorashのブログ • メタプログラミングでActiveRecord::Enumの値についてカラムにコメントする - patorashのブログ • コメントのないカラムを抽出してマイグレーション処理を生成する - patorashのブロ グ • カラムだけでなく、テーブルにもコメントを追加する - patorashのブログ • オープンセミナー2020@岡山 - connpass