Melting Pot of Thoughts

SaaSスタートアップのCTOです。思考の整理のため考えたことをメモとしてアウトプットしていくブログです。

プルリクへのセルフコメントという小技

プログラミングにおいて、お気に入りのよく使っている小技として「プルリクにセルフコメントしまくる」という小技があります。

良いプルリクの作り方については検索すれば色々ネット上に情報が転がっているのですが(説明文の書き方、PR分割の方針…etc)、セルフコメントについてはあまり見たことがないのでTipsとして取り上げてみました。

 

※ 前提:各用語は以下の意味で使っています。

  • 「プルリク」はGithubのプルリクスト(=マージリクエスト)のことを指します
  • 「セルフコメント」は自分で作ったプルリクエストのコード差分行やあるいはプルリク全体に対しコメントをつけることを指します。

 

セルフコメントにおいては、「レビュアーへの質問」「レビュアーへの説明(修正背景の意図など)」「やり残したTODOの備忘メモ(例:マージ後XXXしないといけない)」などを書きます。
これをすると以下のメリットが得られます。

メリット1. コメントをつけると、レビュアーに意図が伝わりやすくなり、レビュアーにとってもレビューしやすくなる

これは一番想像つきやすいメリットかと思います。
コードの修正背景をレビュアーが想像するのではなく、コメントすることで、誤解も起きない上理解しやすいプルリクエストになります。

メリット2. 修正意図のコメントがドキュメントの代わりとなる

メリット1ではレビュアーに意図を伝えるためと書きましたが、遠い将来誰かが修正意図を確認する手助けとなることもあります。
「コミットメッセージは修正背景がわかるように書くべき」という言葉もありますが、プルリクのコメントであればコミットメッセージよりさらに大きな情報量のコメントを残せます。

メリット3. コメントをつけると、その箇所はレビュアーに見てもらえる

レビュアーとしてはコメントをつけてもらっている箇所には必ず目を通します。
そのため自分が自信のない箇所にコメントをつけておけば、自然とその箇所が重点的なレビューをされることになるため、ミスもみつかりやすくなります。

メリット4. コメントをつけるとセルフレビューになる

個人的にはこれが最大レベルのメリットだと思っています。

ブログなどの文章を書くとき同様、コードもまずはガッと勢いで書ききって、その後自分で内容確認しながら修正・リファクタ・テスト等していくプロセスをたどる人は多いかと思います。
そんな中、プルリクのコードを1行1行丁寧に見ながらセルフコメントをつけていく作業をすると、コードを書くときとは別の頭脳が働き、立ち止まって自分自身のコードを俯瞰して見れます。それにより実装中には気づかなかったバグに気づいたり設計・実装の改善を思いついたりすることがよくあります

さらにいうと、レビュー作業自体がコードの課題点を言語化し分析する作業なので、自身のスキルアップにも繋がります。

メリット5. 備忘としてやるべきことをコメントすることで、やり残し漏れも防げる

修正範囲の大きい実装に集中していると、どうしても修正漏れなどが起きてしまいがちです。
ソースコードにTODOコメントとして残しておき、マージまでにそれを解消するという手が使えますが、TODOコメントではせいぜい数行の情報しか残せません。

私はWIPでプルリクを作って、やるべきことを備忘コメントとして残しておくということも行ったりしていますが、結構ありだと思います(これは個人の好みによると思います)。

 

 

以上がプルリクへのセルフコメントのメリットでした。

自身の経験に照らし合わせると、特にOSSのプルリクはコメントを書かない人が多いように思います。自分でOSSを作ってメンテしている身からすると、知らない人から来た説明一切無しのPRは慎重に見ないといけないためコメントはあったほうがいいなと思っています。

業務コードについては社内の人間同士なので、レビューしていてわからない点は気軽に質問できますが、レビュアーが忙しいときには「よくわからないのでヨシ!」とスルーしPRのApproveをしたくなる気持ちも人間なので起きてしまいます。
セルフコメントはそういった事態を防ぐ意味でも便利な小技かなと思っています。