猫でもわかるWebプログラミングと副業

本業エンジニアリングマネージャー。副業Webエンジニア。Web開発のヒントや、副業、日常生活のことを書きます。

実装についての相談会をするときの資料に何を書くべきか

f:id:yoshiki_utakata:20181018231309j:plain

はじめに

「ここの実装どうしたらいいんだろう」「ここの仕様はどうしたらいいんだろう」といった相談をすることはエンジニアではよくあると思います。そういった相談をするときにどうしたらいいのか。相談のミーティングを開くとして、どのような資料を作っていったらいいのか、について、Webエンジニアの私が気をつけていることをまとめます。

相談会をする際の心構え

実装の相談会をするのはなぜか

なぜ相談会をするのかを考えることが重要です。実装がOKなのかNGなのかを確認するだけならコードレビューで十分です。しかし、コードレビューで本当に深い話をしようとするとコメントがぐちゃぐちゃになってきますし、時間もかかります。また、コードレビューは必ずしも全員が見るとは限りません。*1

そこで僕は、以下のような場合はチーム全員を集めてのミーティングで「相談会」をすることにしています。

  • APIの仕様のような、他のチームに利用してもらう部分のため、容易に変更できない箇所を実装しようとしている。
  • サービスの核となる部分や影響の大きな部分を実装ようとしており、未来に負債にならないように慎重に実装したい。

また、相談会をすることで実装の方針がチーム全員に共有されるので、「私はAというモデリングをしていたけどあの人はBというモデリングをしていた」といった矛盾が減ります。

他にも、自分が気づいていなかった仕様漏れに気づいたり、他人の経験則を活かすことができます。

  • ここにはこういう仕様があるので今考えている実装だと間違っています
  • 過去このような実装をしたことがあるのですが、こういうケースが出てきて困りました
  • こういう実装をしておいたらこういうケースでも対応できたので良いです

このように自分の設計ミスなどに事前に気づくことができる効果もあります。

まず自分が相談内容について詳しくなる必要がある

しかし、何も考えずに相談会をすればいいわけでもありません。適当に相談会を開くと、相談したい問題についてチーム全員で悩んでしまい、結局何も決まらずに時間だけが過ぎてしまいます。

そこでまず重要なのが、自分が誰よりも相談内容に詳しくなることです。「この相談会で何を決めたいのか」をはっきりさせてください。この後具体的な相談資料について書いていきますが、それに沿って資料を書いているうちに、自分が相談したいことがなにかわかってくるはずです。

自分が会議の主催者です。会議の進行方向をしっかりコントロールできるように、「自分が最終的に何を決定したいのか」だけは頭に入れておいてください。

他人は何も詳しくないことを理解する

もう一つ重要なのは、「他人は何も理解していない」ことを理解することです。自分が知っていることは全部他人も知っている、と思っていると痛い目を見ます。「他人は何もしらない」ということを理解してください。丁寧すぎるくらい説明をしてください。

相談資料に書くべきこと

相談するにあたり相談資料を作成することをおすすめします。先程も言ったように他人は何も理解していないので説明する必要がありますし、何より自分の考えの整理に役に立ちます。

いきさつ・何をしたいのか

例: 「Aという機能を実現する必要があり、そのためにBのAPIを実装しようと考えています。Bを実装するためにCという機能が必要になるのですが、このCの実装で悩んでいます。」

目的や自分が考えている手段を明確にします。いきさつや目的によって手段が変わる場合がありますので、まずここを説明しておくのが重要です。もしかしたら「そのCいらなくない?」なんて意見が飛び出すかもしれません。

相談会の参加者が話に入ってきやすくなる効果もあると思っています。

何を決めたいのか

例:「Cをどのようなインタフェースにするか悩んでいますので、これを決定したいです。」

後に「案」を出しますが、「何を決めたいか」と「案」はセットで考えます。

前提知識

例: 「XとYはこういう仕様の違いがありますので、~の機能を再利用することはできません。」

決めたいことに対するシステム的な制約や前提知識を説明します。

案がないまま相談すると議論が迷走したり意見が出てこなかったりするので、たたき台となる案を1つか2つを用意しておきます。案があると「この案はこの点がだめ」「この案はこの点が良い」といった「いい/だめ」の議論になります。そしてその「いい」「だめ」に対して「この点において良い」「この点においてだめ」と意見が出しやすくなります。最低限以下は用意しておきましょう

  • 案を1つか2つ。最大4つくらい
    • 多ければいいというわけではない。明らかにダメな案は削っておくこと。
  • 各案のメリット・デメリット
    • デメリットのない案があるならそれを選べばいいだけなので、メリットとデメリットがあるはずです
  • 自分はどれがいいと考えているかとその理由
    • 案が無いのは論外ですが、案があっても参加者はどれがいいのか悩んでしまいます。
    • 主催者の意見があると、それに対して「その案でいい」「それよりこっちのほうがこういう点でいい」と議論がしやすいです。

ではより具体的に例で考えてみましょう。

例: APIレスポンスのJSONの構造に悩んでいる

いきさつ: twitterの「フォロワー一覧」を見られる機能を実装しようとしています。「フォロワー一覧ページ」には「フォロワー一覧」「自分のフォロー数」「自分のフォロワー数」を表示する必要があり、私はこれを表示するためのAPIを実装しようとしています。

何を決めたいのか: 「フォロワー一覧ページ」なので「フォロワー一覧 API」は必要なのですが、「フォロー数」「フォロワー数」を「フォロワー一覧APIに乗せる」か、「フォロー数とフォロワー数 API」を別に作成するかで悩んでいます。

前提知識: フォロー一覧APIはこの画面以外で使うことも想定しており、その画面ではフォロー数やフォロワー数は必要ありません。フォロー数とフォロワー数の取得はそれなりにDB負荷がかかります。

案:

  • 案1: 「フォロー一覧API」で「フォロー数」「フォロワー数」を返してしまう。
    • メリット: フォロー一覧画面に必要な情報を1リクエストで取得できる
    • デメリット: フォロー一覧画面でこのAPIを利用する場合「フォロー数」と「フォロワー数」は必要ないがDBに負荷だけかかってしまう
  • 案2: 「フォロー数フォロワー数API」を別に用意する
    • メリット: フォロー数フォロワー数が不要なページで無駄にDB負荷がかからない
    • デメリット: APIを2回叩かないとフォロワー一覧画面が表示できない。片方のAPIだけコケた場合のエラーハンドリングが面倒。

おまけ: 相談会をしやすい環境

ミーティングって結構コストが高いんですよね。コードレビューのほうが気楽なので、大事なことだと思いつつついついコードレビューで済ませてしまったりします。そこで、定期的に「みんなでコードレビューを見る会」をしたり、週一で「相談会のための時間」を確保するなどして、相談がしやすい環境づくりをしていくことも重要でしょう。

Web API: The Good Parts

Web API: The Good Parts

*1:チームの方針にもよるのですが、全員のレビューを必須にしていたら開発はめちゃめちゃスローになってしまうでしょう。