クラウドワークスでエンジニアをしている八木 ( @negito6 )です。
私は最近、コメントをきちんと書くことに凝っています。コメントとは、ソースコード中に書いてコードの意図を説明したり、バージョン管理におけるコミットの説明を記述する、謂わば「注釈」のことを指します。
そこで本記事では、コメントを書くときの私なりのこだわりについて、紹介いたします。なんか長ったらしく書いています（自分でもそう思います）が、特に会社で強制しているわけではなく、今のところ私個人のポリシーです。（記事を書いた目的は、最後のほうをお読みください。）
なお、バージョン管理のツールは git および GitHub の例を用いてお話しします。ご自身の環境に合わせて適宜読み替えていただけると幸いです。
何を目指して書くか
想像してみましょう。時は金曜日の21:30。オフィスに居るエンジニアは自分一人。鳴り止まないアラート。他部署の人も何やら困っている。ユーザーからの問い合わせも増えているらしい。
最近開発内で勢力が拡大している酒クラスタ*1が飲み会中で、チャットに書き込む人もいない。目の前にあるソースを読むしかないが、見慣れないライブラリ、小耳に挟んだ社内用語、特別なデータがないと通過しない if 文、何を意味しているか分からないテスト。。。
そんな経験をしたこと、ないでしょうか。（※※※弊社での内情ではありません※※※）
少ない人数で、不慣れな領域の障害対応をしなければならないときは、ソースコード以外の情報が欲しくなります。
コメントを書くことのメリットはさまざまあると思いますが、私は「障害対応のため」に、もっと言うと「障害対応時の情報収集効率を上げるため」に絞って書くことにしています。それが、コメントの恩恵が一番大きいシチュエーションであると考えられるからです。
目的を絞る理由は、迷う要素を極力減らすためです。ただ漫然とコメントを書こうとしても、「前後のソースを読めば分かるんじゃないか」とか「ここに書かずに、別途仕様ドキュメントを作ったほういいのではないか」とか「とりあえず困ったら自分に聞いてもらえばいいかな」とか、色々と考え始めてしまうことがあります。しかし障害対応に目的を絞れば、万が一のときに欲しいと思われる情報を書くということに集中できます*2。
障害は突然やってきます。自分のコミットの問題について、自分が常にアドバイスできるとは限りません。そんなときのためにコメントを書いておけば、過去と未来で情報交換をすることができます。仮に普段の開発には役に立たなくても、当たれば非常にリターンの大きい投資ですね。
この記事は、孤軍奮闘でコメント書いてる人、もしくは、書こうと思うものの迷ってしまいなかなか書けていない人にとって、役に立つかもしれない記事です。
- コメント書く派 |- 周りも巻き込んでる派 |- 孤軍奮闘派 <---- ここの人 `- 周りは気にしない派 - コメント書かない派 |- 書こうと思うけど書かない派 <---- ここの人 `- 書くべきではない派
ちなみに、「コメントには、変更の内容ではなく変更の理由を書こう」という話があると思いますが、その手の説明は色々なところで見かけるので、今回はあまり触れていません。
ツールごとに見えかたを考える
一口にコメントといっても、シチュエーションによって、見えるもの、見たいものが違います。
git log / git show でコミットメッセージを見る場合
コミットメッセージを見るときは、どんな情報がほしいでしょうか。私がコミットメッセージを見るのは、「ある変更が、なんのために入れた変更か」を知りたいときです。 Pull Request の diff が読みづらく変更点をコミットごとに知りたいときや、 git blame して特定の行の変更理由を知りたいときなどです。
コミット履歴は時間軸方向のデータを扱うので、 before / after の情報を含むことが望ましいでしょう。書くべきは、
- コミット適用前の挙動
- それでサービス上困っていること
- コミット適用後の挙動
といったところでしょうか。
エラーが起きているのであれば、エラーの重要部分を貼って、「それが解消される」ということを記載しておけば充分だと思います。
