yigarashiのブログ

学んだことや考えていることを書きます

開発の導入準備おすすめ仕草3つ

最近、自分が先行して開発をして、地盤が整ったところで他のメンバーにも開発タスクをやってもらうという場面があった。特に、チームでは経験のないツールを使ったデータ基盤に関するタスクであったので、手厚く導入をすることが重要であった。その時の準備が好評で開発体制の素早い拡大につながったので、おすすめ仕草として3つまとめておく。改めて整理したら自分も十分には書けていない項目があったのであとで直しておこうと思う。

その1: いわゆるREADME

まずは最も当たり障りのないところから。以下のような内容をざっくりまとめる。

  • 何のために作っているか
  • どんなミドルウェアを使っているか
  • 何をしているか
  • 主要なディレクトリの説明
  • 環境構築
  • 実際に動かせるサンプル

特に「実際に動かせるサンプル」は大事だと思う。多くのOSSが当たり前に備えている「Getting Started」の項目に相当するもので、そのリポジトリの動作イメージが一気に具体的になるし、コードリーディングの起点にもなるので準備できると良いと思う。Webアプリケーションなんかはとりあえずローカルで起動することになるので忘れがちだが、試しに変更を加えてみるチュートリアルを置いておくといったことで同じ効果が期待できるだろう。

その2: サンドボックス

好きに変更して動作確認をできる環境を用意するのは一般に良いことだと思う。特に、クラウドサービスを使いまくったバッチ処理のような場面ではサンドボックスを用意するのも一手間かかるので、本番で試行錯誤のイテレーションを回してしまいそうになるが、やはり手元で好きにできるに越したことはない。その1で実際に動かせるサンプルを作るために、そうした環境が自動的に必要になる可能性も高い。ローカルでは本番と違う設定やコマンドが必要になるケースもあるのでそういったものも準備しておく。

今回のケースでは、異常なデータを再現しやすいようにdocker-composeでMySQLも立てられるようにしておいて、さらにサンドボックスを充実させたりしている。

その3: 作業ログ

典型的なタスクについて、一連の作業手順をメモしまくったログを残しておくと良い。例えば自分の場合は以下のような内容をひたすら書いておいたところ、それを後追いするだけで開発を進めてもらえた。

  • 認証のためのトークンをxxから取得
  • ooのホストに向けて以下のSQLを叩いて件数を確認
  • 設定のooをxxに変えておいて動作確認する
  • 件数が多いので設定の--をxxにしておく

特に、事前調査の方法や実装方針の選択は暗黙知になりやすいので、そういった内容が現れるように意識して書くと良い。自分の体験だと、どのDBホストでどのくらい好き勝手にクエリを投げて良いかといった感覚を醸成するのが難しかったので、作業ログでSELECT COUNT(*) FROM xxxとかしている様子が書いてあるのは、単に何をしたら良いかわかる以上の効果があると思う(主に新人向け)。


以上!良いドキュメントを書くとスムーズに開発が広がってみんなが幸せになるので、いろんなテクを駆使して書いていきましょう。