本題に入る前に言葉の定義について

一般的には、技術的負債という言い方のほうが馴染みが良いと思うのですが

「技術」という単語が出るとどうしても「エンジニアだけのお仕事」という感じになってしまう。その時は他施策より優先度が下がることが多い気がする。
技術的負債の代替語でサービス負債という単語を考えてみた

という記事を読んで自分もこの考えに結構近い所あって、特に最後に

特に攻めの施策ばかりやっていて、守りが薄くなってるところはいいのではないだろうか。
技術的負債の代替語でサービス負債という単語を考えてみた

というのがすごく腹落ちすることが多いので、これ以降はサービス負債という言い方をしていきます。

対象となるWebサービスの状況を簡単に

フリーランスになって色々なWebサービス開発のお手伝いをしてきてますが、その中で一番長く関わってる所は

・2013年にサービス開始。
・当初はRails3で開発をはじめ、Rails4にアップグレードして、今に至ってる
・サービスの成長にいたる過程で、各種機能開発を行ってきた結果として、ModelとControllerがそれぞれ100を超える

という感じで俗に言うサービス負債をそれなりに抱えてます。

途中でピボットされて、ターゲットユーザーが変化したことで、色々と謎な仕様とか仕組みが多く、結果としてそれがサービス負債になってる印象が、お手伝い開始してからの最初の１～２年は結構ありました。

当時に比べると最近はかなり状況改善されてきたなぁーと実感することが多くなったのでこれまでにやってきて良かったと思えることをまとめてみます。

良かったことを先にリストアップ

大きくは以下の3つになります。

・利用者視点で重要な機能だけひとまずインテグレーションテスト書く
・サービス開発・運用に大事なドキュメントの整備
・Railsの設計方針を言語化

利用者視点で重要な機能だけひとまずインテグレーションテスト書く

とある機能の処理が肥大化していて
・何百行にも及ぶメソッド
・なぜそのような処理をしてるのかすぐに理解できないようなビジネスロジック
という箇所があって、この部分に関しての改修とか追加機能がちょいちょい発生していました。

こういう状態になってるコードなので、予想通り（？）テストもほとんどなかったので、ちょっとづつインテグレーションテストを書いていき、結果としてだんだんとそこの機能に関する仕様の理解が出来た気がします。

※ 当時はあまり意識してなかったのですが、今振り返ると

不整合を起こさず、仕様追加や変更に役立つ文書を作る良い方法があります。それが、「仕様化テスト（characterization test）」を作ることです。
「レガシーコード改善ガイド」のススメ
第2回：コードを理解するため、仕様化テストで文書化する

ということを愚直にやっていたんですね。

サービス開発・運用に大事なドキュメントの整備

エンジニアチーム内だけではなく、それ以外のチーム間で共通の認識が持てるようにするためにもドキュメントの整備は大事かなと思ってます。

ドキュメント整備においては

・関係する人の中で共通イメージを持つために作るもの（一度作ったらメンテナンスされることが少ないかもしれないので自分が使い慣れてるツールで早くまとめることの方が重要）
・リファクタリング等で内部の処理が変更された時にメンテされることが想定されるもの（メンテナンスしやすい仕組を利用することが重要）

という観点に分けて整理していきました。

共通イメージを持つためにまとめてるドキュメント

私は、Macで普段開発をしてて、以前から各種資料はKeynoteを使ってまとめてきてるので

・機能ｘ利用者軸でサービスをサブシステム単位でまとめた図
・業務フローとシステムの対応関係まとめた図
・ネットワーク構成図

みたいなものは、自分なりのデザインパターンがあるので、比較的サクッとまとめることができます。

既存の課題なんかを話し合う時に、どういう部分に影響が出るかを共通認識持てやすくなると思っており、こういう形で可視化出来たのは個人的にかなり良かったと思ってます

Railsの設計方針を言語化

関わってるサービスの特性考えると

- 予約系の処理
- 決済処理

に関わるModel/Controllerが特にFat化してる傾向にありました。

ここの処理についての改修や機能追加の話が出ると「xxxのメソッドを呼ぶ所だから作業見積もりしづらい・・・」というような話題が必ず出るような状況で、おそらくこういうのはどこの現場でもあることなのかなと思います。

設計方針について特に整理したものが存在してなかったので、結果として今のような状況になってしまったと判断して以下の様なことをしながらちょっとづつ設計方針をまとめていきました。

・一定規模のRailsの設計方針について触れてる記事を読む
・自分たちと似たような概念の仕組みを持ったRailsベースのアプリケーションのサンプルをGitHubで探す。

discourseは規模が大きいのでこれを参考にしたのですが、自分が関わってるサービスの特性考えると、参考になる設計が少なかったので、深くはチェックしませんでした。

それよりも、Take My Moneyという書籍のサンプルコードを見てて、特に決済まわりの設計がとても参考になったのでこれをすごく参考にしました

まとめた設計方針

社内のQiitaTeamに以下のようなことをまとめてます。

・Railsを深く知らない人でもある程度開発できる領域を増やす
・これまでの反省を踏まえてカジュアルにgemを導入しない
・MVC層にこだわらない設計方針
・特定のModelが肥大化して役割を持ちすぎる傾向にあるため必要に応じてapp/validators層（カスタムバリデーションが多数ある場合）やapp/queries層（複数のModelの値を参照しないと取得できない複雑な検索処理）に処理をうつすことを考える

設計方針に関することは他にもあるのでそれはまた別の機会に書くことにします。

まとめ

Webサービスを継続して運用していく中でサービス負債はちょっとづつ溜まっていくと思いますが、実際に

・利用者視点で重要な機能だけひとまずインテグレーションテスト書く
・サービス開発・運用に大事なドキュメントの整備
・Railsの設計方針を言語化

という３つを行ったことでちょっとづつですが、サービスに関わる人同士のコミュニケーションがやりやすくなったように思うのでこの記事が似たような境遇の人やチームのヒントとか考えるきっかけになればと思ってます！