はじめに
こんにちは！フルサポート開発チーム、エンジニアの下山です。
最近は猛暑のせいでバイクに乗る回数が極端に減っています。早くライダーに優しい気温の季節になってほしいです🥵
本記事でお話すること
今回は、フルサポート開発チームがメインで取り扱う管理画面※1のコーディングルールについてお話します。
ただし、コーディングルールの詳細については触れません。
では何の話をするかというと、そのコーディングルールができるまでの経緯とか背景とか目的とか…
そういった事細かにまとめられる機会のあまりない内容についてお伝えしたいと思います。
※1：管理画面とは弊社スタッフが利用する社内アプリケーションの総称です。
声があがるまでの経緯
つい最近まで管理画面には明確かつ詳細なコーディングルールは用意されていない状態でした。
ルールを作ろうという声があがったきっかけは、管理画面のバックエンド側のコード（REST API）をアプリケーション分割しているときでした。
アプリケーションの背景
最初は管理画面を含む弊社のすべてのアプリケーションのコードを1つのリポジトリで管理していました。
顧客にいち早く新たなサービスを提供できるように、開発もなるべく速度を優先して機能の追加や改善を行っていたこともあってか、ルールのない状態で開発は進み、ばらつきのあるコードが点在する巨大なアプリケーションへと成長していきます。
2020年にこのモノリスをマルチプロダクト化に合わせてドメインごとに部分的に切り出し始めました。
管理画面のコードも別リポジトリに移行しましたが、大半のコードはあくまで移行したにすぎず、カオスさも引き継がれたままでした。
他方でシステムの中でも特に重要な機能については、コード移行時に再設計して作られました。
再設計をする際には既存のコードに合わせるべきか、大幅な変更を加えるのか、変更するならどういったアーキテクチャを採用するかなどの検討コストがかかりました。
再設計されたコードは元のコードよりも相当綺麗なものになりましたが、機能ごとに最適化された設計であり汎用的なものではありませんでした。
課題
上記のような背景によって、管理画面のコードは2パターンに大別されるようになります。
1つは既存のさまざまな設計思想がある無秩序なコード、もう1つはある特定の機能に対して一定の秩序が設けられたコードです。
これによって開発者は迷いが生じやすくなります。
例えば、新しいAPIを実装するとなった際に既存コードの中でどのコードを参考にすればよいのかという判断が必要になります。
直近で実装されたものを参考にすればよいのですが、その中でも機能の複雑度によっては設計の厳密さが異なっており、自分が実装するものに対して最適なお手本探しが必要になります。
もし判断に確信が持てない場合は、別の人に聞いたり一緒に検討したりする、なんてこともありえます。
開発者体験は悪く感じることでしょう。
迷いによって、コードリーディングやコミュニケーションのコストが発生し、それが設計・実装の遅延の元となっていました。
ルール策定、ドキュメント作成へ
こうしてコードの再設計をきっかけに課題が浮き彫りとなり、チームの定例でルールの策定の話題が持ち上がりました。
議論・検討に参加する有志を募り、ルール策定・ドキュメント作成が開始されました。
主な目的は2つです。
1つはアーキテクチャやコーディングスタイルの共通認識を作り、迷いを減らし設計・実装のコストを減らすこと。
もう1つはメンテナンス性の向上。
アーキテクチャの統一でロジック調査・再設計・修正が容易になり、コーディングスタイルの統一で致命的なエラーやインシデントを回避したり可読性を向上させたりすることが期待できます。
数名で議論・検討しながらルールのドキュメントを作成、できあがったものをチームに共有、確定して運用、といった流れでした。
各々自分のメインタスクを抱えている中で作っていくものだったので、明確な期限は決めずに進めていきました。
（並行してdjango-stubs, Ruffの導入検討も行われ、Ruffについては採用し現在も利用しています）
コーディングルール
定義すべきルールが何かを検討するために、以下の観点で課題を洗い出しました。
根本となるアーキテクチャパターンについては、以下の理由でCQRSパターンをベースにしていくことになりました。
- APIのロジックをシンプルに保つ
- データベースアクセス処理を記述する箇所を統一する
CQRSパターンに則る形で、ディレクトリ構造とファイル・クラスの命名規則についてルールを定めました。
ルールに則りながら特定の機能のAPIを実装しつつ、その実装内容をもとにドキュメントを整形し、また実装を進めていくといった感じで、繰り返しながら内容をブラッシュアップしました。
最終的には実際にAPIを実装する手順という形でコーディングルールのドキュメントが作成されました。
処理フローを説明した上で、新規API作成時の ルールを記載したものです。
サンプルコードも逐一書かれているので、このドキュメントを参照することで誰でも一通りの実装ができると見込めます。
コーディングスタイル
コーディングスタイルもコーディングルールと同様に、現状のコードからわかる問題点を一通り調査し、それらをガイドラインの見出しとしました。
コーディングスタイルが乱れている実例に基づき見出し項目としているため、具体的で細かい内容の項目もあります。
例えばログ出力において各レベルでどのような内容を記載するか、ユニットテストにおいてのクラス名・assertion・バリデーションのルールなどです。
import文、 変数・引数名の書き方などの一般的なルールも一部取り上げていますが、Google Python Style Guideのように多岐に渡る項目を網羅していません。
また、全体的に記載されている項目数も多くありません。
迷いを減らすことを目的としているため、既存コードを参照した際にばらつきのあるスタイルにのみ言及するようにしました。
ルールを守るべき温度感を表す指標については、Essential（必須）とStrongly Recommended（強く推奨）のみに絞りました（Vue.jsのStyle Guideを参考にして設定）。
RecommendやUse with Cautionぐらいの温度感の低めな指標が存在すると、その他のケースを許すことに繋がり統一性がなくなるので上記2つの指標に集約しています。
その他
コーディングルールに基づいて実装すると、重複したビジネスロジックが作られてしまう懸念もあったため、各APIが共通で利用したいロジックについてはドメインモデルを作成する、というルールも設けられました。
ドキュメントにはドメインモデルの責務やコーディングルールを記載しています。
また、既存のコードについて詳述するドキュメントも作成しました。
利用頻度が高く、特有の背景を補足する必要があるロジックについてまとめたもので、既存コードを修正する、あるいは部分的に利用する際の道しるべとなる想定です。
運用中
策定したコーディングルールの運用を始めてから約1年、コーディングスタイルについては約半年となりますが、ルール策定以前よりも滞りなく開発が進められるようなったと思います。
現状、ルールの大幅な修正は行われていませんが、必要があれば適宜改善していく方針となっています。
このルールは管理画面のコードに触れる全員が責任を負う意識のもと、「誰かが作ったルールに従っただけ」といった他責思考にならず、疑問や問題点があればメンバーに相談しチーム全員でメンテナンスしていくスタンスです。
個人レベルのコードの疑問を取っ掛かりとしてチーム全体のルールの改善に繋げられるよう、日々のお仕事をがんばりたいですね💪
おわりに
ここまでの内容で、管理画面のコーディングルールができるまでの経緯・背景・目的といった内容をご紹介できたかと思います。
フルサポート開発チームは、既存のコード・開発環境を改善しつつ、弊社スタッフがより効率的にサービスのオペレーションを遂行できるよう、機能の実装・修正を行っています。
やりたいことは盛りだくさんですが、圧倒的リソース不足…！
ということで締めの言葉になります。
ビザスクではエンジニアの仲間を募集しています！ 少しでもビザスク開発組織にご興味を持たれた方は、ぜひ一度カジュアルにお話ししましょう！ developer-recruit.visasq.works
