まとめ

この記事ではtoB SaaSのスタートアップで筆者がより良いコードベースを実現するために、実際に実践している内容を記載しています。
プログラムを実装する際には、実装速度より、読みやすいコードを重視すべきであるという考え方と理由を記載しています。
混沌としてきてしまったコードベースから抜け出す最初のステップとして、「どのように書くか」「どこに書くか」を"チームで一致させる"ことから始めると良いという考え方と理由を記載しています。
実践内容の紹介と、それによって得た効果・問題点や感想を論じています。

本文

背景

MVP開発開始から2年余り、弊社SaaSプロダクト「Proceedクラウド」はこれまで機能拡張を積極的におこなってきた中で、コードベースはいわゆる「技術的負債」が溜まってきてしまっている状態です。状況を改善するために開発チームとして認識を合わせ、以下のような取り組みを実践しています。

実装の速さより読みやすさを重視する

特にアジャイルでのSaaS開発においては、ソースコードの大部分は何度も繰り返し読まれ、保守され、改修されていきます。たとえ実装に手間や時間がかかるとしても、ソースコードが読みやすくなる・保守改修しやすくなるなるのであれば、開発組織全体で見た総合的にかかる長期的なコスト（=その機能のために費やす時間）は短くなります。したがって東京ファクトリーでは、手早く機能を実装することよりも、時間がかかっても読みやすいコードを書くことに重きを置いています。

一般的に読みやすいコードを記述するためには、リーダブルコードなどの優れた書籍や、各言語のベストプラクティスなどを参考にするとよいでしょう。一方で全てのエンジニアあらゆる観点から常に読みやすいコードを書くのは、容易ではありませんし、開発する対象や開発手法・チームによって効果の出やすい点は変わってきます。

「どのように書くか」「どこに書くか」をチームで一致させる

「読みやすいコード」を書いたとしても他の人から人から見たら読みやすいコードではないかもしれません。たとえ読みやすい綺麗なコードを書く技術を究めたとしても、どのような視点で問題を捉えて分割していくかによって、読みやすいコードは変わってくるはずです。したがって継続的なチーム開発の中では、各々が綺麗なコードを書くスキルを身につけることに加えて、「チームの誰が書いても同じようなコードになる」ように仕組みを作っていくことが大切です。

また、読みやすいコードを実現するための観点として、大きく以下の2点が挙げられると考えています。

コードを読んで機能の内容がすぐにわかること
各機能のコードがどこにあるかすぐにわかること

これらは、プログラムを実装するときの言葉に置き換えると、 1. はコードをどのように書くか、2. はコードをどこに書くかということに対応しています。これらをチームで一致させることて「（チームにとって）読みやすいコード」を実現させることができます。

実際の取り組み（命名規則とモジュール依存制約）

段階的に（かつ効果的に）読みやすいコードの実現を目指すために、変数名等の命名規則と、各モジュールの配置規則を作成しています。

コードをどのように書くかという観点では、まずは変数名や関数名が適切に名付けられることが大切であると考えています。「適切な名付け」には用語集や他のソースコードとの整合性も観点に含まれるため、適切に名付けられれば統一された実装になりやすくなります。命名規則を用意し、コードを読んで機能の内容がすぐにわかるように試みています。

コードをどこに書くかという観点では、アプリケーション全体としてはクリーンアーキテクチャベースでのレイヤ定義を行い、フロントエンドコンポーネントについては関心を持つモデル単位でのパッケージ切り分けを行なっています。例えば新しく機能追加するときには、どこにコードを追加すべきかをなるべく一意に特定できるように心がけています。また一部各モジュールから依存できるパッケージをLinterでルールとして設定し、規則に則らないコードを機械的に検知できる仕組みを試験的に導入しています。

効果と感想

上記の考え方を実践し、3ヶ月程度経過したころから全体的にポジティブな効果があったと感じています。改善前の定量的な指標が取れておらず比較はできていませんが、体感として、目的としていたオンボーディングやキャッチアップの高速化・コードレビューの時間の短縮・デグレの減少（レビュー段階で捕捉しやすくなった）が実現できたと強く感じています。コーディングルールを決めていくことで、実装にかかる時間が長くなる、といった問題なども今のところ(1年弱)感じていません。

副次的な効果として、コードレビューで指摘すべき範囲がレビュアー（筆者自身）の中で明確にできたことで、悩むことが減りました。コードレビューでは、レビュアーがこだわればいくらでも指摘点を挙げることができてしまう、といったことが一般に起こりがちだと思っています。そのためどこかで線引きを行う必要がありますが、これまでは変数名や関数名の適切さよりも個別のロジックが最適に組まれているかに（個人的な関心が強く）より目が向いてしまう傾向がありました。この記事にある考え方を社内に向けて整理・明文化する中で、細かいロジックの最適化よりも適切な変数名を与えることをより重視するようになり、コードレビューで指摘すべきこと・しなくて良いことが明確になってレビューが行いやすくなりました。

問題点として、いろいろな規則を文書化し共有してもなかなか実践・浸透させることが当初は困難であったことが挙げられます。それぞれの規則の背景や考え方を共有するために、理由などを説明した詳細なドキュメントを作成しましたが、あまり定着しませんでした。解決策として、背景などを省略し、要点のみを実例と共にチートシートとして１ページにまとめて共有したところ、だいぶ改善されたように感じました。より良いコード、というテーマは抽象的な議論になりがちなので、まず簡単に実践ができるようにして効果を体感しながら進めていくのが効果的で、その結果として背景なども体感しながら理解してもらいやすいのかもと感じました。（チートシートを作成する、という方法は、このトピックに限らず社内で非常に有効に機能しています。チートシートの作成やドキュメンテーションについての考え方については今後別途記事を作成し紹介します。）