Hatena::Groupbugrammer

蟲!虫!蟲!

Esehara Profile Site (by Heroku) / Github / bookable.jp (My Service)
過去の記事一覧はこちら

なにかあったら「えせはら あっと Gmail」まで送って頂ければ幸いです。
株式会社マリーチでは、Pythonやdjango、また自然言語処理を使ったお仕事を探しています

 | 

2013-05-07

[] Redmine等のチケットの書き方について、特に自分の考えをまとめるという観点から 00:14

 多くの開発会社にて、恐らくRedmineなどの「チケット管理システム」を使用して、作業の内容であったり、バグの内容を管理していることが多いかと思います。その一方で、改めて考えてみると「自分はこういう観点からチケットを書くようにするといいと思っている」という話については、余り共有されない部分もあるのかなーというのが、実際のRedmineの運用を見ていて思ったりもするので、提案とまではいかないけど、「自分はこういう風に書いた方がいいのかな」と思う所を列挙してみます。

「チケットを書くこと」によって、自分の考えをまとめる

 例えば、バグ報告の場合なんかに顕著かも知れませんが、「チケットを書くこと」というのは、「何かしらの情報を伝える」という形で運用をしているところもあるかもしれません。状況によりけりなので、どう言いようも無いですが、自分が「チケットを書く」ことになった場合、「自分はこのように考えている」ということをまとめるために使うことが多いな、と。

 テスト駆動開発の場合もそうなのですが、なぜ先に「テスト」を書くのか、というと、たぶん「テスト」を書くことによって、「いまから実装しようとしているものが、どういう形をとっているべきか」というのを具体的に考えるための方法、という一側面はあると思います。同じように、チケットも「いまから作業しようとしている、あるいは伝えようとしていることはどういうことなのか」ということを具体的に考えるためのきっかけだろうと思います。

なにかおかしいなと思う問題を書く場合

 例えば、「なんか変な動きをしている箇所があるな、これって本当だったらこうするべきなんじゃないの?」というのをチケットに書き起こすとするなら、出来るなら下のような構成にしたいなあと、自分は思ってます。

  • その動作を発生させるための手順
  • その中で、自分が問題と思っている箇所
  • その問題と思っている箇所は、実際にどういう風になっているべきか
  • そしてその理由

 この四つが重要かなと思う理由なのですが、まず一つに、挙動に問題があるとするならば、その挙動は他人も同じような状態が体験できなければなりません。ですので、自分と同じ体験をしてもらうための前提として、その手順を書きます。

 しかし、これだけでは足りない。というのも、「自分が問題だと思っているし、他人もそう思うはずだ」という前提でやってみても、他人にとっては全く「問題」ではないということが往々にしてあります。だから、まず最初に「何が問題だ」と思っているかを伝えるべきなのかな、と思っています。相手がどう思うかであれ、自分にとって問題があるかどうかだけは伝わります。

 もしかしたら「その挙動が実際にどうなっているべきなのか」についてはかかなくてもいいかもしれません。先に仕様であったり、あからさまに動きがおかしい場合で、なんとなく「正しい動き」がわかるなら、それも明記すると、どういう風にしたいのかが、明確になっていいかもしれません。また、できるならば、そのように変更するべき理由もあると、より問題の焦点が明確になるかなと思います。

 上記の話は、なんだか「他人に説明するような形」になっていますが、それは自分に対しても同様です。自分もなにか考えてはいるんだけど、口を開いた途端に言葉が上手くでてこないことがあります。そういうときは、とりあえずこの場では「自分がこの問題についてよくわかっていないからだ」という風に考えることにします。つまり、ちゃんと「人に説明できる」ということは、自分なりに「他人に伝えやすいように問題を把握している」とも言える、とそのように考えます。

 ですから、逆にチケットを先に書く時に、「他人に説得するように書いてみる」と、自分の場合だと問題点が明確になって良いチケットだなあと思ったりします。

作業内容を書く場合

 自分の考えをまとめる、という意味ではこっちのほうがよりその傾向が強いと思います。例えば、作業の前に、その作業内容に説明することを推奨するような「チケット駆動開発」だったりすると、まず最初に作業内容をチケットに起こしてから、実際の作業に移るというフローになるかと思います。で、こっちのほうが「何の為にチケットを書いているのか」というのが書いている本人からすると不透明になりやすかったりするのかな、と思ったりします。(実際に、そういう話が出ていたりしました)

 例えば、自分の会社だったりすると、下のようなテンプレートを用意していたりします。

  • その作業にかかる工程
  • 実現されるべきユーザーストーリー
  • 画面やURIなどの実装
  • 内部設計について
  • 確認項目

 上記の場合は、チケットに起こす単位が、gitのbranchごとだったりします。これは、基本的には「feature MTG」と呼ばれる、10分から20分程度の実装確認のミーティングのあとに発行されるものです。ですので、議事録的な意味もあるのかな、という気がしています。

 以前に、手習いみたいな形でチケット駆動もどきみたいなことをやっていましたが、その時に思ったのは、「自分がやろうとしている過程を、自分に対して改めて説明しなおすことで形にする」というのを意識すればいいのかな、と思ったりします。具体的には次のような形を考えたりします。

  • いまからどのような機能を実装しようとしているのが
  • その機能が実装されると、何が嬉しいのか
  • どのような方針で機能を作ろうとしているのか
  • その機能は、正しく実装されているなら、どういう挙動をするのか

 どんな機能であれ、その機能が実装されるということは、その機能を実装するための「理由」がある筈です。多くの場合、それは仕様と呼ばれるものですが、仕様上で、なぜそれが要求されているのか、わかるとするならば、それも咀嚼できるなら、できたほうがいいのかなと。あとどのような方針で機能を作ろうとしているのか、というのは、単純にどういうロジックなのか、アルゴリズムなのか、ということを簡単に書くということかなと。

 で、その機能を実現された、というためには、何かしら、「外から見える何かの動きを行なっている」ということに言えるのかな、と。

おまけ:そのチケットの概要が三行でわかる概要をつけてみる。

 よく新聞記事のライティングの方法で紹介されているのですが、最初に「その記事にはどんなことが書いてあるのか」という概要を書いておき、その概要で興味をもった読者に対して、詳細を続けて書くと言うことをやるそうです。ネット上のブログ記事でも、最初に概要が書いてあるものがありますね。個人的には、この構成が好きなので、チケットの場合には、書く余裕があるときは書くようにするといいのかな、と思ったりもします。

とはいえ、チケットを書くのは面倒くさい

 で、上記は「おれがかんがえるさいきょうのチケットのかきかた」ではありますが、他の記事も当然ながら、参考にしています。例えば、クリアコードの記事は下の通りです。

 自分としては、クリアコードのチケットの書き方は丁寧でいいなあ、と思うのですが、やはり丁寧になればなるほど、「面倒くさい」という部分が出てきてしまうというところだと思います。現実問題として、例えば「どういう風に実装するか」を考えるために、ノートの紙の上で書いたりすることは、自分にはよくあります。その上、それを言葉にして書き直すのって、「やっぱり面倒くさいな」というのが正直なところです。

 ただ、単純に「面倒くさい」と済ますよりは、「自分の考えを整理するために、言葉にしたほうがいいよね」と思って書いた方が、自分にとってメリットがあるかなと思うし、そういう風に書いたら、ちょっとはチケットを書くことの意味が明確になるのかな、と思って今回の記事を書きました。

 何かの参考になれば幸いです、

蛇足: 付箋

 で、蛇足なんですが、「チケットにするまでもない、些細な変更点」であったり、あるいは「作業中に見つかった他の問題点」については、基本的に付箋に書くことにしています。というのも、付箋は「書き捨て・メモ」といったり、あるいは「明確にはなってないけど何となくこの辺が問題なのではないか」という曖昧な事項をメモしておくのに使ったりします。そういう意味で、ちょっとした使い分けというか、メモ用紙があると便利なのかなという気はしています。

 |