Zenn
📡

開発もコードレビューも最後には「優しさに溢れたコメント」だよね、という話

2024/10/08に公開
JavaScript
TypeScript
VS Code 拡張機能
心理的安全性
tech

はじめに

皆さんはちゃんとコメント残していますか？
新しくコードを追加した時、自分だけはその意味をよく分かっているため、よほど意識的にならないと「客観的にこのコード見たらどうか？」ということに考えが至らない場合が多いです。
熟練のエンジニアでも陥りがちですから、新人は言わずもがなでしょう。

コメントを残す主なメリットは次の通りです。

  • 他の人の理解にかかる時間を短縮する（自分も含む）
  • 誤解を防ぎ、人為的なミスを減らす
  • 心理的安全性の向上

ここに過去の自分が知っておきたかった「新人が知っておくべきコメント」について3つを紹介しておきます。
※ 普段フロントエンドエンジニアをやっているためコードはTypeScriptベースです

コード内のコメント

メソッドに対するコメント

新しくメソッドを追加した時。なぜそのメソッドを用意したのか？何を渡して何を返すメソッドなのか？大きく複雑な処理をしているほど理解に時間がかかってしまいがちです。

そんな時はJsDocコメントを活用しましょう。コメント部分を/** */で囲う書き方です。
関数の説明に加えて、@param（引数）や@returns（返り値）にその型や値の一例を書いておくと、理解も一瞬でできてしまいます。
このJsDocsのすごいところはそれだけではありません。関数名にカーソルを当てると、コメント部分が説明として表示されます。メソッドを別ファイルからimportして使う時など、これほど強力な機能はありません。

/**
   * 記事が一件以上取得されているか否か
   * @type {boolean}
   */
  const existsArticle = !!data.items.length
  
/**
   * URLのクエリパラメータを対応するフィルターの数値配列に変換
   * @param value 例: 15
   * @returns 例:[0,1,2,3]
   */
  const translateQueryToFilter = (value: string | null) => {
    return Number(value)
      .toString(2)
      .split('')
      .reverse()
      .flatMap((n, index) => (Number(n) === 1 ? index : []))
  }

アノテーションコメント

開発時、後で修正の必要があるコードや改良点はあるけど時間がないので後回しにしたいことが出てくる場合があります。
そんな時はアノテーションコメントを使いましょう。

// TODO: 処理が冗長なので後でリファクタする
const create = (userId: number) => { ...

// FIXME: なぜか動作が重いため調査と修正をする
const update = (userId: number) => { ...

/**
* ユーザー情報を消去する
* NOTE: 
* @params userId ユーザーID
*/
const delete = (userId: number) => { ...

アノテーションコメントにはコメントの分類をするという目的に加えて、コメントを目立ちやすくして見落としを防ぐ役割があります。

たとえば、VScodeでは TODO Highlight や Todo Tree といった拡張機能を入れることで、修正ポイントがあることが一目で分かるようになります。
https://marketplace.visualstudio.com/items?itemName=wayou.vscode-todo-highlight
https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree

プロジェクトごとに必要なアノテーションコメントをカスタマイズしておくのも良いでしょう

 "todohighlight.keywords": [
    {
      "backgroundColor": "#ffa500",
      "color": "white",
      "text": "TODO:"
    },
    {
      "backgroundColor": "#00bfff",
      "color": "white",
      "text": "NOTE:"
    },
    {
      "backgroundColor": "#00bfff",
      "color": "white",
      "text": "MEMO:"
    },
    {
      "backgroundColor": "#66cdaa",
      "color": "white",
      "text": "HACK:"
    }
  ],

コミット時のコメント

git commit -m "..."でコミットメッセージを残すことは、もはや常識にも近いですが、もっと改良を加えましょう。

コミットメッセージにPrefixをつけることでどういったコードを追加削除したのか、一目で分かるようになります。
導入する時はプロジェクトルールとしてREADMEなどに下記リンクと共に記載すると良いでしょう。

Prefix 意味
feat 新規機能
fix バグ修正
docs ドキュメント変更
style コードのフォーマット
refactor 機能の変更を伴わないコードの改善
test テストの追加・修正
chore ビルドツールやライブラリで自動生成されたもの 
git commit -m "feat: ページネーション機能を新規追加"
git commit -m "refactor: ユーザー情報変更の処理をページから分離"
git commit -m "docs: createメソッドに説明を追加"

プレフィックスとしては以下のSemantic Commit Messagesが有名です。
他にも種類があるので興味があれば調べてみてください。

Semantic Commit Messages
https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716

プルリクエスト時のコメント

自分がPRを出す側のとき

PR（プルリクエスト）を出す時、レビュアーの理解を助けるコメントを充実させることはマナーです。
加えて、マージのし忘れ・誤ったマージをしてしまうことを防ぎましょう。ブランチが作業中であってもPRを出しておくことで、作業進捗が分かりやすくなり、並行作業が多い時にマージのし忘れも防ぐことができます。

事前に出しておくPRのタイトルには、WIP(Work in Progress) をつけることで「将来的にマージのためのPRを出すけど今はまだ作業中」という意味を表すことができます。WIP: Titleや[WIP] Titleのように書くのが一般的です。
これは、GitHubのDraft Pull Requestの機能を使っても同じ意味になります。

[WIP]検索機能の追加

自分がレビューする側のとき

他の人が出したプルリクエストに対してレビューコメントをするとき、単調なコメントだと温度感が伝わりづらいです。
緊急で直した方が良いのか、それとも直した方がベター程度のものなのか...案外伝わらないものです。
そういったときはコードレビューのコメントに略語を付けましょう。

[IMO] letではなくconstを使うように変更したほうが良いですね！
略 語源 意味
IMO In my opinion 私個人の意見としては
NITS nitpick 指摘するほどでもないかも
Q Question 質問なのですが
LGTM Looks Good To Me 拝見しましたが良いと思います！

自分がよく使うのは上記ですが、以下の記事が他のコメントに詳しいので、覚えて活用してみてはどうでしょうか？
https://zenn.dev/chamo/articles/f2740957e10519

さいごに

チームでの開発時に便利なコメントについて、意外と知らない人も多いのではないかと思ってまとめました。
なにより、過去の自分が知りたかった内容になっています。

ここまで紹介しておきながら、一番大事なのはハック的な知識よりも「どうすれば分かりやすいか？」を常に考え続ける姿勢だと思っています。
他者と未来の自分を思いやる心（コメント）を忘れずに！

Happy Hacking!

Discussion