Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

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

Shingo Tomioka

July 29, 2023
Tweet

More Decks by Shingo Tomioka

Other Decks in Programming

Transcript

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

    View Slide

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

    View Slide

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

    View Slide

  4. 解決策
    各モデルのソースコードの先頭に、
    モデルの概要と各カラムの説明をコメントで書く
    © 2023 Wantedly, Inc.

    例: app/models/candidacy.rb の先頭に...

    View Slide

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

    View Slide

  6. ③ 各カラムの説明
    解決策
    © 2023 Wantedly, Inc.

    ④ 今は使われてないカラム
    の説明

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  11. 結果
    開発もデータ分析も一定効率が上がった
    © 2023 Wantedly, Inc.

    View Slide

  12. 社内の声を抜粋 ①
    © 2023 Wantedly, Inc.

    View Slide

  13. 社内の声を抜粋 ②
    © 2023 Wantedly, Inc.

    View Slide

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

    View Slide

  15. なぜ自然に書くムーブが起きるようになってきたか
    © 2023 Wantedly, Inc.

    View Slide

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

    View Slide