モデルの説明コメントを書く文化が会社に浸透してきた話

TokyuRuby会議14 の LT (5分) で話したスライドです。
https://tokyurubykaigi.github.io/tokyu14/

1. © 2023 Wantedly, Inc. モデルの説明コメントを書く文化 が会社に浸透してきた話 TokyuRuby会議14 LT Jul. 29 2023 - 富岡 真悟
2. 自己紹介 © 2023 Wantedly, Inc. 富岡 真悟 Wantedly, Inc. (2017~)
3. 3~4年くらい前から顕著になってきた課題 モデルに関するドメイン知識がわからなくて 開発やデータ分析の効率が下がる • コードベースの大規模化 ◦ → 各メンバーが触ったことがない領域が増加 ◦ メインの Rails アプリのモデル数が 400くらい • メンバーの入れ替わりの増加 ◦ 初期の土台を作ったメンバーの退職 ◦ 専門の PdM、データサイエンティスト、データアナリストなどもジョイン • コロナによるリモートワークの開始 ◦ → 詳しい人にさっと聞きにいく、がやりにくくなった © 2023 Wantedly, Inc. 背景 例:「このモデル何？」「このカラム何？」「このカラムが NULL になるのってどういうとき？」 ...
4. 解決策 各モデルのソースコードの先頭に、 モデルの概要と各カラムの説明をコメントで書く © 2023 Wantedly, Inc. ⁝ 例: app/models/candidacy.rb の先頭に...
5. 解決策 © 2023 Wantedly, Inc. ① モデル名と日本語名 ② モデルの概要 • どういう役割を持つのか • どういうときに作成/更新/ 削除されるのか • 外部ドキュメントのリンク • etc. ⁝
6. ③ 各カラムの説明 解決策 © 2023 Wantedly, Inc. ⁝ ④ 今は使われてないカラム の説明
7. • 実装に近い場所にあるので、 ◦ 参照しやすい ◦ 更新されやすい = 風化しにくい ソースコードにコメントで書くことの利点 - 外部ドキュメントに書く場合と比較して © 2023 Wantedly, Inc.
8. ただし モデルの数が膨大 (400くらい)。 一つ一つ調べて書いていくのは 手間がかかる... © 2023 Wantedly, Inc.
9. どのように増やしてきたか • 毎月の負債返済日に書く • 調べたときについでに書く • 詳しくない領域を触ることになったときに調べて書く • 退職する人に詳しいところを書いていってもらう • etc. © 2023 Wantedly, Inc.
10. 取り組みを開始してから約3年 - 今どれくらいになったか • 重要度の高いモデルはおおよそカバーされてきた • 割合で言うと2割くらい ◦ 100% にならなくてもいい © 2023 Wantedly, Inc.
11. 結果 開発もデータ分析も一定効率が上がった © 2023 Wantedly, Inc.
12. 社内の声を抜粋 ① © 2023 Wantedly, Inc.
13. 社内の声を抜粋 ② © 2023 Wantedly, Inc.
14. • あんまり詳しくない領域を触ることになったときにばっと調 べて書く、というムーブが自然に起きるようになってきた ◦ 「◯◯機能のリニューアルをするので、土台作りに、モデルを調べ てコメント書きます」 ◦ 書くということが文化して根付いてきた 個人的によかったと思っていること © 2023 Wantedly, Inc.
15. なぜ自然に書くムーブが起きるようになってきたか © 2023 Wantedly, Inc.
16. まとめ © 2023 Wantedly, Inc. • 開発やデータ分析をしやすくするために、モデルのソースコードにコメント で説明を書く取り組みを始めた • 2~3年かけて、皆が恩恵を感じるようになり、書くことが文化として浸透し てきた