コメントはどこまで書くべき？実務経験を通して考えた「ちょうどいいコメント」
開発業務の中で地味に悩ましいのが「コードコメントの分量と内容」です。
まったくコメントがないと後から読みにくい、でも過剰すぎると読解の邪魔になることも…。
今回は、実務を通して感じた「ちょうどよいコメントのあり方」について、自分なりの視点で整理してみたいと思います。
目次
コメントがあることで助かることも多い
これまで複数のプロジェクトに関わる中で、コードコメントに対する方針はチームや案件によって様々でした。
中にはコメントが極端に少なく、全体の仕様や意図を読み解くのに時間がかかったこともあります。
たとえば、Reactのコードで useState(false) となっていた初期値を true に変更した際に「この変更の理由をコメントに書いてほしい」と指摘されたことがありました。
一見シンプルな変更ですが、Reactにあまり慣れていない方にとっては「どうしてそうしたのか」が分かりにくく、コメントがあることでチーム全体の理解促進につながることもあります。
このように、コメントは“保険”のような役割を果たす場面があり、特にメンバーの経験値がバラつく現場では重要な情報共有手段になり得ます。
とはいえ“書かなくてもいいコメント”もある
一方で、すべてのコードにコメントをつける必要はないとも思っています。
if (isAdmin) {
// 管理者だった場合
doSomething();
}
このように、コードをそのまま言い換えただけのコメントは、あまり意味を成しません。
むしろ変数名や関数名を工夫することで、コード自体を“コメントのいらない文章”のようにすることが理想です。
const MAX_RETRY_COUNT = 3;
if (retryCount > MAX_RETRY_COUNT) {
// これ以上は再試行しない
return;
}
このように意図が明確な命名を心がけることで、コメントの必要性がグッと減ることもあります。
JSXやフォーム周辺は補足コメントがあると親切
とくにReactなどでフォームを扱う場合、JSXや構造が抽象的なケースでは補足コメントがあると助かります。
たとえば、複数の管理者区分を扱うようなフォームで、変数名が mng1 や mng2 など抽象的になっている場合、コメントで「管理者」「管理責任者」などと補足してくれていると、コードの意図を掴みやすくなります。
また、次のような例ではどうでしょうか。
{formItems.map((item) => (
<label key={item.name}>
{t(item.label)}
<input type=”text” name={item.name} />
</label>
))}
一見きれいに見えますが、「これはどこのフォーム？」がコード上から読み取りにくいという課題もあります。
とくに管理者や責任者など似たような役割の入力項目がある場合、 mng1、mng2など変数名が抽象的であるとますます混乱しやすくなります。
このようなケースでは、JSX上に軽くコメントを添えて補足しておくだけでも、可読性は大きく向上します。
{/* 管理責任者セクション */}
{formItems.map((item) => (
<label key={item.name}>
{t(item.label)}
<input type=”text” name={item.name} />
</label>
))}
「誰が見てもすぐに把握できる」構造でない場合は、“少し先回りした気配り”が読みやすさにつながることを、実務で改めて実感しました。
コメントの目的は“未来の誰か”のために
コメントを書く・書かないは、開発者のスタイルにもよりますが、共通して言えるのは“未来の誰か”がコードを読むときの助けになるかどうかです。
それは自分自身かもしれないし、チームの別の誰かかもしれません。
とくに以下のような場面では、コメントの有無が保守性を左右すると感じています。
・ビジネスロジックが複雑な条件分岐
・複数の入力・出力を持つ関数
・フォームや画面構成が抽象化されている部分（例：mapでフォーム生成）
・案件固有の名称・処理・制約が含まれている部分
おわりに
「読めばわかるコードを書くこと」と「必要に応じたコメントを書くこと」は、どちらも大切な開発スキルです。
すべての人が同じ知識・経験値を持っているわけではないからこそ、ちょっとした補足がチーム開発では非常に有効です。
過不足なく、気遣いあるコメントが書けるよう、これからも自分なりの工夫を続けていきたいと思います。
