✨

【開発手法】Continuous Collaboration のすすめ ベストプラクティス編

に公開

はじめに

https://zenn.dev/noranuko13/articles/b30c8ed65e8e27

対象

  • 途中から参画した開発者が即戦力になれるプロジェクトを目指したい方向け。

CI/CD

  • CI(継続的インテグレーション、Continuous Integration)
    • 文法チェック・フォーマッター・自動テスト・ビルドなど。
  • CD(継続的デリバリー、Continuous Delivery/Deployment)
    • デプロイ準備・デプロイなど。

https://e-words.jp/w/CI-CD.html

お馴染みCI/CDです。イケてる現場だと完全自動化されています。恐らく様々な書籍やブログでベストプラクティスと喧伝されたのが大きいでしょう。少なくともWebアプリの世界では、大人の事情でやれない理由はあっても、やらない理由はないのかなと思います。

本記事は新たに、

  • CC(継続的コラボレーション、Continuous Collaboration)
    • 開発環境構築・ドキュメント・開発フロー・テスト・初期設定など。

の追加概念を提唱するものであります。

CC

Collaboration(コラボレーション)という英単語には、協調・共働などの意味があります。ITエンジニアであれば、GitHubのCollaborator(コラボレーター)が馴染み深いでしょうか。

Continuous Collaboration(継続的コラボレーション、以下CC)とはその名の通り、「継続的に共に働くための自動化・環境整備」のことを指します。造語です。検索してみたところ、一部の論文や記事で使われてるくらいで定義はないようですが、既にあったらごめんなさい。

参画しやすいプロジェクトにはいくつかの共通点が存在します。幸か不幸か、ピンからキリまで様々なプロジェクトに参画してきた筆者が、その経験を元に基本的な項目を抽出してまとめてみようと思います。

継続的コラボレーションの実践例

どの項目からでも読めます。順番に特に意味はありません。

開発環境構築

README.mdに以下の項目を記載しておきます。

  • Requirements: 推奨動作環境、満たすべき要件など。
  • Installation: 手動インストールが必要なツール類やその手順。
  • Setup: セットアップコマンド、具体的な手順など。

基本はリンク先の手順を参照で構いませんが、バージョン指定など通常と異なる方法の場合は理由と詳細を書いておきたいです。結論、シンプルなWebアプリであればコマンド一発で立ち上がるのが理想。どこまで手順を削れるかは腕の見せどころ。

また開発環境を部分的に作り直す作業、サーバー再起動後の立ち上がり速度など、開発作業中のロスをいかに省けるかは、作業効率に直結します。特にデータベース・ストレージの作り直しなど、使用頻度の高いものは最適化・手順化しておくことが望ましいです。

ドキュメント

徹底的にドキュメントの自動生成ツールを活用します。データベース定義書・API仕様書・ライブラリのリファレンスなど、ソースコード上での修正が自動で反映されるものが望ましいです。コーディングルールについても、文法チェッカーやフォーマッターを基本とします。

  • データベース定義書: A5:SQL Mk-2, tbls
  • API仕様書: OpenAPI, Swagger
  • リファレンス: Javadoc, TypeDoc

手動更新に頼ったドキュメントは、その場限りの使い捨てと割り切るか、一定期間ごとに見直しをかけるものとします。例えば機能仕様書やユーザーマニュアルは、リリース時点で同時に最新版への更新を徹底するなどです。

特殊なコーディングルールは、なるべくカスタムルールとして、つまりライブラリの機能で実装して適用するようにします。どうしても機械的な対応が難しいルールに限り、最終手段としてWikiに明文化するくらいで丁度よいです。

開発フロー

開発フローは常に最新の状況を言語化し、Wikiにまとめておきます。中堅レベルのITエンジニアであれば、そのWikiを読むだけで即戦力として活躍できる状態にします。質問があった分かりにくい部分・現状と差異が発生した部分は、小まめに修正を行います。

常に未完成のドキュメントであると意識し、一度作ったら終わりにしないのがポイントです。もし新しい開発フローが発生した場合はWikiに新規追加します。また開発フローが不明瞭な業務が発生している場合は、現状を分析するところから開始します。

Webアプリ開発における開発フローは、末端のメンバーがチケットを割り振られてから、本番リリース終了後までに負う作業でまとめます。例えば以下の視点です。

  • チケットのステータス・担当者を変更するタイミング。
  • Gitにおける一連の流れ(ブランチの作成からマージまで)。
  • 手動テスト、ステージング環境への反映確認などを行うタイミング。

テスト

ローカル環境で動作確認や試験が直ちに行えない状況を避けます(極稀に本当にステージング・本番環境でしか確認が行えない機能がありますが、そういった例外は除きます)。外部サービスに依存する場合はモックやダミーのAPIサーバーを作り、なるべく同じ状態で開発を行います。

全ての機能に自動テストがある状態を目指します。カバレッジ100%を目指すのではなく、顧客に提供している機能が正常に動作しているか確認する、という視点が良いです。特に不具合がクリティカルな機能の場合は、入念にテストコードを実装しておくといいでしょう。

開発環境の初期データおよびパターン別のサンプルデータ投入コマンドもあると便利です。投入用のCSVファイルや画像、PDFファイルなども忘れずに。アプリ設定・個人設定の区分値により挙動が異なるWebアプリであれば、パターンごとに用意されていると楽です。

どうしても厳しい場合は、データ登録の手順を記したMarkdownファイルを合わせてコミットする形を取ると良いでしょう。

初期設定

プロジェクトに参画した直後に行う作業を、ここでは初期設定と呼称します。

  • 各種アカウント発行・二要素認証などの設定。
  • チャットツールのチャンネルやストレージ・ドライブへの招待。
  • 各種ツールの権限設定。

セキュリティ上、自動化もできず、参画者自身が手動で対応するしかありません。このため必要な作業をWikiにまとめておく必要があります。作業内容をTODOリストとして渡すのはもちろん、管理する企業側もスプレッドシートなどを用意して管理状況を把握しておかなくてはなりません。

できれば企業ドメインの専用メールアドレスを発行し、あらゆる企業アカウントをこのメールアドレスに対して発行するのが手間が少ないです。何より撤退時の削除や無効化が楽になります(GitHubアカウントなどについては相談で)。

https://zenn.dev/noranuko13/articles/d98a25c79e8b14

継続的コラボレーションの習慣化

重要なのは、これらの具体的な継続的コラボレーションの実践例を習慣化することです。プロジェクトを立ち上げた最初だけ、一部の理解しているメンバーだけでは意味がありません。

CI/CDと違い継続が困難な理由は、陳腐化していても気付きにくいからです。CI/CDはエラーを出力して停止しますが、CCはオンボーディングや開発コストの増大など、間接的な損失として見過ごされがち。意識して維持しようとしなければ、簡単に変質します。

最初は期ごとでも構いませんので、定期的にCC(継続的コラボレーション)を見直す機会を設け、少しずつでも共働しやすい環境に持っていきたいものです。

おわりに

半日で初期設定から環境構築まで終わらせて、その後数日はドキュメントとコードを読む時間にできると、いい感じの滑り出しではないでしょうか。参画者のレベルにもよりますが、それ以上かかっているようだと迎える側に課題が隠れている気がします。

快適な状態を維持するためにも、コストは払い続けなければなりません。自浄作用とは少し違うのですが、ホメオスタシスとか恒常性の概念が近いでしょうか。CCが崩れるとプロジェクトが熱中症や糖尿病になる感じ。なのに明確な名称と定義が存在しない。

私個人がさえずっても仕方がないのですが、大事なことなので提唱しておこうと思って書きました。この開発手法が(たとえ何らか別名でも)CI/CDくらい周知されることを祈ります。

関連記事

https://zenn.dev/noranuko13/articles/268191d5c2801b

Discussion