YovStudio

article 読むトレ #05：コメントの過剰サービス

公開日: 2025-06-21著者: Yov in YovStudio

今回のお題コード

AI 「読みやすくなるようにコメントを充実させてみました！どうですか？」

// ユーザーデータをDB含めすべて削除する関数
function deleteUser(userId) {
  // ユーザーIDを受け取る
  const id = userId;

  // ユーザー情報をデータベースから取得する
  const user = getUserFromDB(id);

  // ユーザーが存在するかどうかを確認する
  if (user === null) {
    // 存在しない場合は何もせず終了
    return;
  }

  // ユーザーを非アクティブに設定する
  user.active = false;

  // ユーザー情報をデータベースに保存する
  saveUserToDB(user);

  // ユーザーIDを使ってログインキャッシュを削除する
  clearLoginCache(id);

  // 削除された時間をログに記録する
  logDeletionTime(id);
}

// ユーザー削除処理呼び出し
deleteUser('UID00001');

どう動く？

まず前提として、このコードは getUserFromDB() をはじめ、いくつかの関数の中身が定義されていないので実際に動かすことはできません。
関数の定義は省略されているものとして、処理の流れをイメージしながら読んでみてください。

気になるポイント

さてみなさん、このコードを読んでみて、どう感じましたか？
1 行ずつ親切にコメントが書かれていて読みやすかったでしょうか？

私は以下の点が気になりました。

  • コメントに誤解を招く内容が含まれている
  • コメントがわかりきったことを繰り返している

まずコメントに誤解を招く内容が含まれているのは以下の関数の説明をしているコメントです。

// ユーザーデータをDB含めすべて削除する関数
function deleteUser(userId) {

このコメントをパッとみた印象としては、DBからデータを物理的に削除しそうだなと感じます。しかし処理を読む限り、DBのデータを物理的に削除しているわけではなく、データを残したまま active という値を false に更新して、見かけ上削除しています。いわゆる「論理削除」と呼ばれるものですね。
実務においても、コメントが曖昧だったり誤っていたりで誤解することはよくあります。特に、当初はコメント通りだったけど何らかの理由で修正が入り、時間の余裕がなくコメントがメンテされずに残ってしまっているというケースはあるあるです。

  // ユーザーを非アクティブに設定する
  user.active = false;

  // ユーザー情報をデータベースに保存する
  saveUserToDB(user);

つづいてわかりきったことを繰り返しているについてですが、たとえば以下の 2 行のコメントに書いてあることって、コードを読めば十分に内容がわかりますよね。こうしたコメントは読み手の集中をかえって妨げることがあります。

// ユーザーIDを受け取る
const id = userId;

// ユーザー情報をデータベースから取得する
const user = getUserFromDB(id);

コメントのデメリット

コメントって、読み手の推論コスト（内容を読み解くためのエネルギー）を下げるためのものです。
ですがその反面、コメントには、コード修正時のメンテが地味に面倒で忘れられがち、どうしても目につくため読むテンポが少し遅くなる、さらにコードと矛盾する場合はどちらが正しいのか確認する手間が発生するといった、無視できないデメリットがあります。 これらのデメリットが、実務においては開発者にとって負担になります。「わかりきったことの説明」だけでしかないのであれば、それはノイズになってしまうのです。

私も昔、1 行ずつコメントを書きなさいと教えられたことがあり、今回のコードのようにコメントを書いていたことがあります。ちなみに当時は以下のような背景事情もありました。

  • プログラムの容量にシビアな制限があることも多く、実行コードはなるべく短く書く必要があったため、コメントで補足していた
  • 実コードの行数によって報酬が決まるような契約形態（いわゆるステップ単価制）があり、コードをなるべく短く書き、コメントで補足する文化が一部にあった

これにより実コードはいろいろ短縮されたり、短くするテクニックが駆使され、コメントなしでは読みづらかったのです。

ただ、こういった制約がない状態では、過剰なコメントがかえってノイズになるため、何のためにそのコメントをするのかよく考えた方がよいでしょう。

どう改善する？

コメントは「読み手が迷いそうな部分を補助する」目的で使うのが理想です。 例えば、今回のコードなら自明な部分のコメントをなくし、以下のようにすっきりさせることができます。

// ユーザーを論理削除し、関連データを無効化する
function deleteUser(userId) {
  const user = getUserFromDB(userId);
  if (user === null) {
    // DBにデータがない場合は何もしない
    return;
  }

  user.active = false;
  saveUserToDB(user);
  clearLoginCache(userId);
  logDeletionTime(userId);
}

deleteUser('UID00001');

また、もし「なぜ論理削除なのか」など特別な理由があるなら、その意図だけコメントで補足するのが良いでしょう。

補足：コメントのメンテナンスコスト

人は面倒くさがりです。コメントがメンテナンスされないケースは本当によくあります。 混乱を招くだけのコメントであれば、むしろ無い方がよいこともあります。 だから「本当に必要なことだけ」を、端的に書くようにしましょう。

今回の読みどころ

  • 過剰なコメントは読みづらさの原因になりやすい
  • コメントは「コードの繰り返し」にならないよう気をつける
  • コメントは読み手の理解を助ける「補助線」として使う
  • コメントの内容はメンテナンスしやすいことも大切
list 記事一覧に戻る