コメントはコードの理解を助ける重要なツールですが、適切に使わないと逆効果になることも。
この記事では、過剰なコメントや不要なコメントを避けつつ、良いコメントを書くコツを解説します。
実際のコード例を交えながら学びましょう！
プログラミングを学び始めた頃、誰もが一度は「コメントはたくさん書けばいい」と思いがち。
しかし、コメントには適切な書き方と役割があります。
今回は、新人エンジニアのタロウと先輩エンジニアのアヤコが、良いコメントとは何かを考えます。
彼らの会話を通して、あなたも「なぜ」を説明するコメント術をマスターしましょう！
アヤコ先輩、コードにコメントを書くのが大事だって聞いたんですが…。
レビューで「コメントが多いよ」って言われちゃいました…。
コメントはたくさん書いたほうがいいんじゃないんですか？
アヤコ
コメントは確かに大事だよ。
ただし、量が多いだけでは逆効果になることもあるよ。
良いコメントっていうのは、コードの「なぜ」を説明するもの。
逆に、コードそのものをただ言い換えただけのコメントは意味がないの。
過剰なコメントは、コードを読む人にとってノイズになります。
コードが何をしているかを説明するコメントは、コードそのものがわかりやすければ不要です。
NG例：コードをそのまま言い換えたコメント
# 変数xに値10を代入する x = 10 # xに1を加算する x += 1
OK例：コードの意図や背景を説明するコメント
# ユーザーがログインした後に初期化する値 x = 10 # カウントアップすることで次の処理を制御 x += 1
コメントを書くときは「このコードが何をしているか」ではなく、
「なぜこうしているのか」に焦点を当てるといいよ！
コードを書き換えると、コメントがコードと一致しなくなることがあります。
古いコメントが残ったままだと、かえって誤解を招く原因になります。
コメントのメンテナンスも重要です。
NG例：古いコメントが残ったコード
# 旧バージョンではここでユーザーを認証していた authenticate_user() # 現在は廃止済み
OK例：不要なコメントを削除し、シンプルにする
authenticate_user() # 現在の仕様に基づいた認証
コメントもコードの一部。
使わなくなったコードを削除するときは、関連するコメントも忘れずに整理してね。
「なぜこのコードを書いたのか」という背景や目的を説明するコメントは、
未来の自分や他の開発者にとって貴重な情報源です。
NG例：意図が伝わらないコメント
# 負の値を処理 if value < 0: handle_negative_value(value)
OK例：背景や意図を説明するコメント
# クライアントからの要望で負の値を許容する仕様に変更 if value < 0: handle_negative_value(value)
コメントは未来の読者、つまりあなた自身や同僚のために書くもの。
「なぜこのコードが必要なのか」を丁寧に伝えるのがコツだよ。
コメントはコードの補足説明として重要な役割を果たしますが、適切な量と質が求められます。
過剰なコメントや古いコメントを避けつつ、背景や意図をしっかり伝えるコメントを書きましょう。
タロウのように、コードとコメントのバランスを取れるエンジニアを目指してみてください！
コメント