@kyanny's blog

My thoughts, my life. Views/opinions are my own.

イシュー(チケット)のタイトルには「現状どのように間違っているか」を書くべきか「本来どのようであるべきか」を書くべきか

イシュー(チケット)のタイトルに、

「(本来ならばこれこれこういう振る舞いであるべきだが、現状だと)これこれこのように間違った振る舞いをしている(のでバグである)」

という風に書く人と、

「(本来ならば)これこれこういう振る舞いであるべき(だが、現状だとこれこれこのように間違った振る舞いをしているのでバグである)」

という風に書く人がいる。これは混乱を招きやすい。英語で書かれていると「べき」などがよく抜け落ちるので混乱に拍車がかかる。

タイトルを見たときに、「タイトルで述べられていることは間違いである、ので修正すべきである」と解釈するのと、「タイトルで述べられていることは正しい、しかし現状そうなっていないので修正すべきである」と解釈するのでは、全く真逆の意味になってしまう。

イシュー(チケット)の本文がスクリーンショットやスクリーンキャストのみで補足説明のコメントがないと余計に混乱を招く。最悪の場合、勘違いして真逆のバグ修正をしてしまい、一仕事終わってから気づく、ということも起こりうる。

ベストな解決策は as-is と to-be のいずれも省略せずに、

「本来ならばこれこれこういう振る舞いであるべきだが、現状だとこれこれこのように間違った振る舞いをしている(のでバグである)」

という風に冗長だが明瞭な書き方をすべきだ。また、タイトルと重複していたとしても本文に改めて

「本来ならばこれこれこういう振る舞いであるべきだが、現状だとこれこれこのように間違った振る舞いをしているのでバグである。」

のように完全なコメントを書くべきだ。

この例の場合、タイトルには「(のでバグである)」という一言が含まれていない。このタイトルを読んだ人はこれがバグ修正の依頼だと確信を持てないかもしれないし、解釈の仕方によってはこれは実装(振る舞い)のバグではなく仕様の間違いを指摘しているのだと誤解するかもしれない。


ブログ記事のタイトルにも同じことが言える。

この記事のタイトルを例にとると、

「イシュー(チケット)のタイトル」

というタイトルは言葉が足りなすぎる。イシューのタイトルが何なのか、がわからないので読み手の想像力を必要以上にかきたててしまう。もしかしたら「イシューのタイトルが面白かった」という笑い話を期待させてしまうかもしれない。

「イシュー(チケット)のタイトルはどう書くべきか」

だと、内容が問題提起であろうことはわかるが、個人的にはまだ物足りなく感じる。そこでこの記事のタイトルに落ち着いた。

「イシュー(チケット)のタイトルには「現状どのように間違っているか」と「本来どのようであるべきか」のどちらか一方ではなく両方を書くべき」

というタイトルであれば、タイトルを読むだけで完結するのでこれが最も良いタイトルだといえるが、せっかくブログを書いている身としてはタイトルだけでなく本文も読んで欲しい。なので読み手にとっては多少不便かもしれないが、ブログ記事のタイトルは少々曖昧さが残っていても良いと思う。