コメントは大事。でも書きすぎも…？

2025年2月24日

こんばんは！IT業界で働くアライグマです！

プログラミングにおいてコードの可読性を向上させるためにコメントを書くことは重要です。しかし、コメントを書きすぎることでかえってコードが読みにくくなったり、メンテナンスが大変になったりすることもあります。本記事では、適切なコメントの書き方や、書きすぎを防ぐポイントについて詳しく解説します。

Contents

コメントを書くべき理由

コメントが重要なのは、多くのエンジニアが認識していることです。適切なコメントは、以下のようなメリットをもたらします。

他のエンジニアや未来の自分がコードを理解しやすくなる のが、コメントの最大の利点です。特に、

などには、適切な説明を加えることで、読み手の負担を軽減できます。

コードの意図が明確であれば、修正や機能追加がしやすくなる という利点もあります。特に、大規模なプロジェクトでは、コメントの有無が開発スピードに影響を与えることも あります。

チームで開発を行う場合、異なるエンジニアが同じコードを触ることが頻繁にあります。その際、適切なコメントがあることで、コードの意図や仕様の理解がしやすくなり、スムーズなコミュニケーションにつながります。

設計書や仕様書がしっかりしている場合でも、コード内に適切なコメントがあることで、実装レベルでの詳細な仕様を補完する ことができます。特に、外部APIの仕様や特殊なビジネスロジックなどは、コメントがあることで後からのメンテナンスが容易になります。

一方で、コメントが多すぎると逆に可読性を損なう ことがあります。

以下のようなコメントは、コードの可読性を下げる原因になります。

// 変数 x に 1 を代入する
$x = 1;

このように、コードを読めば明らかに分かることをコメントするのは無意味 です。コメントは、コードを補足するものとして活用しましょう。

コードとコメントが乖離するリスク もあります。たとえば、コードのロジックが変更されたのに、コメントが更新されていない場合、誤解を招くことになります。

// 配列の要素をソートする
sort($array); // 実際には逆順にソートしている

このように、コメントが間違っていることで、かえってバグを誘発する可能性がある のです。

過剰なコメントは、コードを読み解く際の邪魔 になることがあります。コメントが多すぎると、本当に必要な情報を探しにくくなる ため、結果的に可読性が落ちてしまいます。

では、どのようにコメントを記述するのが適切なのでしょうか。

「なぜこの実装なのか？」 を説明するコメントが最も価値があります。

// 0除算エラーを防ぐため、条件を追加
if ($denominator !== 0) {
    $result = $numerator / $denominator;
}

このように、単なる処理の説明ではなく、その処理がなぜ必要なのか を書くと、意図が伝わりやすくなります。

開発中の課題を明確にするために、TODO や FIXME を活用するのも有効です。

// TODO: パフォーマンスを改善するためにキャッシュを導入
// FIXME: ここでエッジケースに対応できていない可能性がある

このように書くことで、後で見直すべきポイントが明確になる ため、開発の効率が向上します。

関数やクラスの説明には、ドキュメントコメントを使うと効果的 です。

/
* ユーザー情報を取得する
*
* @param int $userId ユーザーID
* @return array ユーザー情報の配列
*/
function getUserInfo($userId) {
// ここに処理を書く
}

このように書くことで、IDEの補助機能が使えたり、自動ドキュメント生成が可能になったりします。

コメントはコードの可読性を向上させるために重要ですが、書きすぎると逆効果になることも あります。

コメントを書く際には、「本当にこのコメントが必要か？」を常に考えながら、適切なバランスを取ることが重要です。