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

© 2023 Wantedly, Inc.
モデルの説明コメントを書く文化
が会社に浸透してきた話
TokyuRuby会議14 LT
Jul. 29 2023 - 富岡真悟

View Slide

自己紹介
富岡真悟
Wantedly, Inc. (2017~)

View Slide

3~4年くらい前から顕著になってきた課題
モデルに関するドメイン知識がわからなくて
開発やデータ分析の効率が下がる
● コードベースの大規模化
○ → 各メンバーが触ったことがない領域が増加
○ メインの Rails アプリのモデル数が 400くらい
● メンバーの入れ替わりの増加
○ 初期の土台を作ったメンバーの退職
○ 専門の PdM、データサイエンティスト、データアナリストなどもジョイン
● コロナによるリモートワークの開始
○ → 詳しい人にさっと聞きにいく、がやりにくくなった
背景
例:「このモデル何？」「このカラム何？」「このカラムが NULL になるのってどういうとき？」 ...

View Slide

解決策
各モデルのソースコードの先頭に、
モデルの概要と各カラムの説明をコメントで書く
⁝
例: app/models/candidacy.rb の先頭に...

View Slide

解決策
① モデル名と日本語名
② モデルの概要
● どういう役割を持つのか
● どういうときに作成/更新/
削除されるのか
● 外部ドキュメントのリンク
● etc.
⁝

View Slide

③ 各カラムの説明
解決策
⁝
④ 今は使われてないカラム
の説明

View Slide

● 実装に近い場所にあるので、
○ 参照しやすい
○ 更新されやすい = 風化しにくい
ソースコードにコメントで書くことの利点 - 外部ドキュメントに書く場合と比較して

View Slide

ただし
モデルの数が膨大 (400くらい)。
一つ一つ調べて書いていくのは
手間がかかる...

View Slide

どのように増やしてきたか
● 毎月の負債返済日に書く
● 調べたときについでに書く
● 詳しくない領域を触ることになったときに調べて書く
● 退職する人に詳しいところを書いていってもらう
● etc.

View Slide

取り組みを開始してから約3年 - 今どれくらいになったか
● 重要度の高いモデルはおおよそカバーされてきた
● 割合で言うと2割くらい
○ 100% にならなくてもいい

View Slide

結果
開発もデータ分析も一定効率が上がった

View Slide

社内の声を抜粋 ①

View Slide

社内の声を抜粋 ②

View Slide

● あんまり詳しくない領域を触ることになったときにばっと調
べて書く、というムーブが自然に起きるようになってきた
○ 「◯◯機能のリニューアルをするので、土台作りに、モデルを調べ
てコメント書きます」
○ 書くということが文化して根付いてきた
個人的によかったと思っていること

View Slide

なぜ自然に書くムーブが起きるようになってきたか

View Slide

まとめ
● 開発やデータ分析をしやすくするために、モデルのソースコードにコメント
で説明を書く取り組みを始めた
● 2~3年かけて、皆が恩恵を感じるようになり、書くことが文化として浸透し
てきた

View Slide

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

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

Shingo Tomioka

More Decks by Shingo Tomioka

Other Decks in Programming

Featured

Transcript