三重の伊賀観光をした

三重の伊賀にいって観光をした。伊賀はとにかく忍者推しという感じで、一貫性があってよかった。

隠れようとして全く隠れられていない忍者。

なぜか目が青くて外人？みたいな忍者。

ポスターもこういう感じで全部忍者な感じ。これ以外もトイレの標識とか、避難の看板とかも全て忍者モチーフで出来ていた。

忍者屋敷にいったのだけど、からくり屋敷があったり、忍者ショーがあったり、手裏剣投げられたりと結構面白かった。あと上野公園でポケモンgoをしたけど、ロコンがいました。

仕様や実装方針の相談をPullRequestで行う取り組み

　これまで少し大きめな機能であれば、コードを書く前にまず仕様や実装の方針をissueのdescriptionにまとめ、それを先にレビューしてもらってから実装にとりかかるということをしていた。最近、その方針をそもそもrepositoryのファイルとして書いて、PullRequestしてレビューしてもらうようにしたら便利だったのでご紹介。

なぜコードを書く前に仕様や実装の方針をレビューするのか

　前提としてなぜコードを書く前に仕様や実装の方針をレビューして欲しいのかについて書いておく。これはとにかく手戻りの量を少なくしたいという要求のためである。

　実装に取り掛かろうとすると、実装の方針はいくつか思いつくが、どれが一番よいか迷うことはよくある。その場合に誰にも相談せず自分だけで判断し、コードを書いてからPullRequestを送った場合、もしその選択に重大なミスがあった場合全て書きなおさないといけない。これは大きな手戻りが発生する。

　このような手戻りを防ぐためには、まずは実装の方針をMarkdownか何かで書き、それを先にレビューしてもらうという手がある。例えば以下のようなフォーマットで書くなどが考えられる。

# 実装方針案1
...

## メリット

## デメリット

# 実装方針案2
...

## メリット

## デメリット

# 検討
案1は工数が非常に少なく済むが、案2のようにしないと今後技術的負債になりうる。
そこで多少大変だとしても、今回は案2の方針で行おうと思うがどうか。

　このフォーマットは単なる例で、その他にもデータのスキーマなどを先に相談したり、処理の流れを日本語で書いてみたりでも良い。いろんな形式で書いて先にレビューしてもらうことで、その時点で筋が悪い部分は指摘され、手戻りの量が少なくなる。

これまではどうしていたか

　これまではこのような実装方針レビューはGithubのissueのdescriptionに書いたり、issueのコメントに書いたりして、issueベースでレビューをしてもらっていた。この方法でも良いのだけど、次の課題があった。

• ある部分が筋が悪いという指摘を書くのに、いちいちその文章を引用してコメントしていて、面倒であった
• 指摘後、実際に修正してもらった時に、その修正点が分かりづらかった
• 新しく入った人に先に実装方針レビューやったほうが良いというアドバイスをしても、その例をissue検索で探して渡す必要があった

課題を解決するために試してみたこと

　これらの課題を解決するために、実装方針レビュー用のディレクトリを作って、そこにMarkdownでファイルを作って、普通のPullRequestベースのレビューでコメントを書いてもらえば良いのでは？と考えた。これは以前別のチームでやっているという話も小耳に挟んでいたので、実際に試してみた。

　次の流れで実装方針をレビューしてもらう。

• docs/spec_review/みたいなディレクトリを作っておく
• そのディレクトリ以下にYYYYmmdd-hoge-spec.mdのようなファイルを配置し、そこに方針を書いていく
• 完成したらいつもどおりPullRequestを送る
• そのファイルに対して、レビュワーにはラインコメントを書いてもらう
• レビューされたら、コメントに返信したり、方針のファイルを変更したりする
• レビューが通ったらmergeする
• あとはそのファイルを見ながら実装する

　このようにすることで先ほど挙げた課題となっていることを解決できた。

• ある部分にコメントするのは普通にラインコメントで良い
• 方針案の修正内容がcommitになるためわかりやすい
• docs/spec_review/以下にどんどん実装方針レビューが溜まっていくため、後から入ってくる人に例として出しやすい

まとめ

　今回は仕様や実装方針相談をPullRequestで行う取り組みについて書いてみた。ちょっと試してみただけだけど、思ったより良い雰囲気だったので、今後も続けていこうと思う。

いつ突然会社をやめても問題ないという基準でコードやドキュメントを書くテクニック

blog.shibayu36.org

　上の記事が思ったより読まれていたので、自分がこの基準を満たせるようにやっているテクニックも箇条書きで書いておく。

• PullRequestを作ったら必ず自分でコードレビューをする
  • コードを書いているとき、その一部一部はこれで完璧と思ってるけど、実は全体を見直すと分かりにくかったりする
• 1日寝てから見直す
  • 1日経つとちょっと忘れて新鮮な気持ちで見れる
• 1週間後にもう一回見てみる
  • 1週間くらい経つともうだいぶ忘れて、穴が見えてくる
  • 穴があったら別PullRequestで直す
• もう一度同じところを担当することがあればチャンス。自分でもこれどういうことだっけってググり始めたら基準を満たせていない
• 自分が全く関わっていない部分のところを触りだしたらかなりチャンス。本当にまっさらな頭で基準を満たすか見れる。他人がやったことだからとか思わずにちゃんとその時に直す
• やったことを全てブログに書いたりや発表したりして、外部にも見せてみて反応を見る
  • 一概には言えないが、反応が悪いなら基準を満たせていない可能性が高い
• もうわかりにくいところはブラックボックス化できるようにライブラリ化する

　まあ他にもいろいろありそう。ライブラリ作るとかは少しハードルが高いものはあるけど、必ず自分でコードレビューするとか1日置いてみるとかはすぐにできることなのでやってみると良さそう。また何回も何回も見なおして直してを繰り返すと、徐々に徐々にではあるけど少しずつコードやドキュメントを書く能力が伸びてくるので、とにかく続けていくしかないと思う。