プルリクであれこれ説明するならコードにコメントに書こう

プルリクで質問されたので返事

seaさん「ぷるりくー、出したー」
landさん「(Github上で) これはなんでこうなの?」
seaさん「(Github上で) あれはこれでこれはあれで」
landさん「(Github上で) ここって本当にこれでいいの?」
seaさん「(Github上で) あれはこれでこれはあれで」
landさん「(Github上で) ちょっとトリッキーだけどいいの?」
seaさん「(Github上で) あれはこれでこれはあれで」
landさん「OK, マージ」
seaさん「やったー」

一年後...

張飛さん「これなんでこうなってんだ?」
関羽さん「いやぁ...わからんなぁ...」

プルリクであらかじめ説明

seaさん「ぷるりくー、出したー」
seaさん「はっ!あれこれ言われる前にちゃんと説明しておこう」
seaさん「(Github上で) あれはこれでこれはあれで」
seaさん「(Github上で) そして、これであれはのれで」
seaさん「(Github上で) でもって、みれでほれはわれで」
landさん「OK, マージ」
seaさん「やったー」

一年後...

馬岱さん「これなんでこうなってんだ?」
魏延さん「いやぁ...わからんなぁ...」

コードのコメントで残したい

まあ、gitの履歴やチケット番号などから追えなくはないですが、あまりフットワークの軽いものではないので、実際に見られることはほとんどないでしょう。そこに求めている情報が確実にあると思わなければ、わざわざ見に行かないでしょう。

なので...

「パッと見て疑問に思われるようなもの」であれば、

ソースコードのコメントで残したい

ものです。

コメントはコミュニケーションツール!

Githubのプルリクレビューの機能が、コミュニケーションツールとしてとっても優秀なので、かなりそこに頼ってしまいがちですが...

ソースコード上のコメントは、
未来の人と通じ合える
優秀なコミュニケーションツール

と言えるでしょう。

事業会社のドキュメント

スタートアップのサービス開発している事業会社だと、ほぼまともなドキュメントは作れません。(作れないかどうかは別としてまず作りません)

それだけに、コミュニケーションから生まれる背景や理由というのは、後から合流した人にとって貴重な情報になります。「なんでこうなってるのかわからないからがんじがらめー」にならないように。

ということが、まさしく、このブログを書くきっかけになりました。

ああ、その会話、もったいない!

そんな感覚。

常に意識しておくこと

質問されたということは、"コードから読み取れない" ということなわけですから、質問された時点でコードを直した方がいいかもしれない、とも言えるわけです。

あらかじめで説明しておこうと思うのであれば、そう思った時点でコードを直した方がいいかもしれない、とも言えるわけです。

(コメントを書くか、リファクタリングするかは選択肢あるとして)

まあ、なんでもかんでもってわけじゃないですが...

Github上でやり取りしたら
「あっ、これはそもそもコメントで書いてたほうがいいな」

ってのを探す習慣を。

そして、これはチャットや口頭でも同じことです。
(あっ、DBコメントもだ!)

f:id:jflute:20150816220833j:plain