【現役エンジニアが考える】ソースコードのコメントについて

【現役エンジニアが考える】ソースコードのコメントについて

「なぜコメントが必要なのか、わからない人」
「ソースコードのコメントに何を書けばいいかわからない人」

そんな方に向けて、記事を書いています。

はじめまして。現役エンジニアのkazと申します。

プログラミングをする中で、自分がコードを書いているとき、他人が書いたソースコードを見たときなどソースコードのコメントに触れる機会って、必ずありますよね。

この記事を読んでいただくことで、ソースコードのコメントに対する疑問を解消します。

ソースコードにおけるコメントは、誰に対して書くのか

私のブログもそうですが、文章を書くときは、相手を意識することが重要です。
相手を意識することで、何を書けばいいかが決まります。

ソースコードのコメントは、システム開発をしてる同じプロジェクトの人、プロジェクトを引き継ぐ人、そして、未来の自分に対して書きます。

プロジェクトメンバーに対して書くのは、難しいと思う方は、未来の自分に対して書いてみることをおすすめします。

自分の書いたコードなのだから、コメントがなくても理解できると思うかもしれませんが、実際は何か月もたった後に自分のコードを読んでもわかりません。

ベテランのエンジニアであれば、自分のコードの書き方や考え方に型があり、そうそう変わるものではないかもしれません。
しかし、プログラミングについて勉強すればするほど、コードの書き方が変わっていきます。
そのため、昔のコードを読んでみると、なぜこんなことが書いてあるのかわからなくなります。

ソースコードにおけるコメントは、何を書くのか

先ほども書きましたがソースコードは、プロジェクトメンバーや自分に対して書きます。

そのため、プログラミング初心者に説明するように細かく書く必要はありません。

事前の知識がなければ、読むのが難しいと思った部分、凝ったコードを書いたことによって読みにくいと感じた部分に対して、説明としてコメントを書きます。

私のイメージでは、教科書にメモ書きをするようなイメージです。
(先生が説明してくれたことの必要な部分だけ書くような感じです。)

コメントによって、次にコードを読む人が読みやすくなるようにコメントを書きましょう。

ソースコードにおけるコメントは、どうやって書くのか

コメントを書く上で決まった書き方は、ありません。

どう書けば、コードが読みやすくなるかを意識すれば、ダメと言われることはないでしょう。

チーム内でコメントを書くルールがある場合は、それに従ってください。

また、ソースコードのコメントを使用して仕様書などを自動で作成するプログラムが存在します。
例えば、javadocです。
このようなプログラムを使用する場合、コメントの書き方をそのプログラムに合わせる必要があります。

【補足】「ソースコードにコメントを書くな」という意見について

ネットを見てみると、ソースコードにコメントは必要ないという意見があります。

「コメントがなくても、読めるソースコード」を書くという意識は、とても大切です。

例えば、関連するコードをブロックごとにまとめて書く、読みやすいようにコードの順序を考えるなどコメントがなくても読みやすくする方法は、多々あります。

読みやすいソースコードを意識せず、すべてをコメントで賄おうとするのは、反対です。

しかし、どうしても事前知識がなければ読めないコードや関数の全体的な説明などコメントがあることで読みやすくなる場合などコメントが必要な場合があります。

私の意見としては、「ソースコードを読みやすく書くという意識を持ったうえで、コメントを書く」ということです。