GitHub Issueコメントに費やすカロリーを増やした結果振り返りやすくなったというお話

GitHub Issueに作業進捗をコメントとしてこまめに書いていた時期がありました。気がつくと短期間で20コメントくらい付いており、内容を読み取るにも各コメントのコンテキスト理解が必要になり、結果大量のノイズと化していました。

フロー型のSNSのノリで書いていたことも原因だったと思います。最近は意識して体裁建てた結果、1コメントに1ページのWikiのようなノリになりつつあります。そんな書くにも悩ましいGitHub Issueのコメントについて、最近構えた個人的な方針を書いてみることにしました。

とりあえずHeaderでタイトルを書く

Issueのタイトルをコメントのタイトルとみるべきである、そう思っていた時期はありました。とんでもない。

コメント自体にもタイトルをつけると読み取りにくくなるのではと思われそうですが、スクリーンショットやコードスニペットを交えているとそれらの意図概要としてタイトルが役立ちます。

例えばSlackにIssue新規コメントを通知していたとして、以下のように流れてきます。

Issueを進めるにあたっての中間段階として何を確認しているのかわかりやすいわけです。

Issue本文のチェックボックス更新時にはコメントにもチェックボックスを追記

Issue本文のチェックボックスを埋めたことを伝えるには、埋めたタイミングで該当チェックボックスを埋めた状態でコメントに記載してみましょう。念の為「IssueのToDoを更新した」と追記しておくとよいでしょう。こうすることで、いつチェックボックスを埋めたのか振り返りやすくなります。

そう、Issue作成時に記載したチェックボックスはいつ埋まったのかわからないのです。

Convert to Issueという機能もありますが、今回の用途だとそもそもConvertする必要がないため無視します。

コメント追記編集は気負わない

下手に半端な新規コメントが大量につく方こそ面倒です。とても読み取りにくくなります。また、Slack通知等で複数のIssueからのコメントが入り混じらないことは保証されていませんから。

テーブルは積極的に使う

表を作るのが面倒で半端なリストにしている場合は、一度SpreadSheet上で整形した上でコピペしましょう。いい具合にGitHub側で解釈してくれます。

あとがき

振り返りやすくすることを念頭においてコメントを書くようにしてみた結果、一つのコメント分量がそこそこ伸びたため、先にdocsとして書き起こしたものへのリンクをコメントに書いたりと、以前よりも読みやすさに気を使うようになりました。

ややCommentを書くだけでも相当カロリーを使うようになった気はしていますが、振り返りやすくなった点をみて悪くはないかなと思っています。Issueコメントに悩んでいる場合の参考になれば幸いです。