たけのこブログ 
プログラミングのコメントの仕方に悩む人
プログラミングをしているときに、正しいコメントの書き方が分からないんだよね。
そもそも、自分が分かっていればコメント書く必要ないんじゃないの？
本記事では「リーダブルコード」を参考に、このようなギモンに答えます。
目次
プログラミングするときの適切なコメントの書き方
僕がプログラミングをし始めたときのこと…
会社で「コメントはできるだけ書くように」と言われ、とりあえずコメントを書いている時期がありました。
しかし、なんとなく書いたコメントは役に立たないだけでなく、読み手の時間をムダにする可能性もあります。
コメントをする理由は、「ソースコードを読む人が最短時間で理解できるようにするため」ということを忘れずにコメントをするようにしましょう。
適切なコメントをするために気をつけることは以下になります。
- コメントするべきで「ない」ことを知る
- コードを書いている時の自分の考えを記録する
- 読み手の立場になって何が必要になるかを考える
コメントするべきで「ない」ことを知る
適切なコメントの書き方を説明するのに、なぜコメントすべきで「ない」こと？と思う方もいるでしょう。
なんでもかんでもコメントを書けばいいというわけではありません。
コメントは、読む人が早く理解するために書くもの。ソースコードを読んですぐに分かることであればコメントする必要はないんですね。
むしろ、コメントを読むことで時間がかかるならば書かないほうがマシということもあります。
例えば、下の例1のコメントは明らかに不要ですよね。画面に情報が増えてソースコードを読む時間が増えてしまう可能性があります。
// Timeクラスを定義する
class Time{
// コンストラクタ
Time();
}意味のないコメントはしないようにしましょう！
コードを書いている時の自分の考えを記録する
ソースコードを書いているときの考えをコメントすることで、あとから読む人の役に立つことがあります。
書いておくと役に立つことは以下のようなことです。
- 色々試した結果
- コードの欠陥
- 定数の理由
サンプルコメントを例2に記載しました。
// ファイルに直接書き込むよりも、メモリ上で書き込んだ方が速い
// TODO:xls形式にも対応する
// 今のサーバーでは最大接続数は1000が限度
const int LIMIT_CONNECTION = 1000;このようなコメントを書いておくことで、あとから読んだ人が「コードを修正する必要があるのか？」「コードを修正したときに問題が起こらないか？」などすぐに理解することが可能になります。
読み手の立場になって何が必要になるかを考える
「初めてソースコードを読む人」がギモンに感じそうなところにコメントを書きましょう。
「初めてソースコードを読む人」というのが重要です。
同じチームで開発している人を想定すると、これくらいは理解してくれるだろうと思ってしまうことがあるはず。
サンプルとして例3を書きました。ここまで書いておけば、「xxxライブラリの中にあるRESTサービスを使っている」ことがすぐに分かるはず。
// xxxライブラリのRESTサービスを利用してログイン認証している
Login(int id, string password)これは実際に僕が体験したことでして。何年間も続いているプロジェクトに途中から参加したとき、グループの人はみんな知ってるものだと思って誰も僕に教えてくれなかったんですよね…。
プログラミングにコメントが必要な理由
ソースコードを見ればプログラミングした内容は分かるから、コメントはいらないと思う人もいるかもしれませんね。
しかし、自分の経験からコメントを書いた方がいい理由が2つあります。
- 1か月後に自分のコードを読んだら忘れている
- 人のコードを読む時間は長い
1か月後に自分のコードを読んだら忘れている
誰もが経験していると思いますが、自分で書いたソースコードでさえすぐに忘れてしまうものですよね。
プログラミング初心者の方は「いやいや自分で書いたことは覚えてるでしょ」と思うかもしれませんが、そのうち経験すると思います。笑
僕は記憶力がないためか、1か月後に自分の書いたソースコードを見て「あれ？こんなコード書いたっけ？」と思うことも…。
まして、何か月も期間があいたら思い出すことが難しい…。
そうなると、自分の書いたソースコードなのにも関わらず、理解するために読まないといけなくなります。時間がもったいないですね。
このときにコメントが書いてあると、プログラミングした内容を思い出しやすい。
ソースコードを読んで理解すれば問題ないのですが、そうなることが予想されるならば、コメントを書いていた方が時間の短縮になります。
自分のためにもコメントを書くことをオススメします。
チームで開発するときにはコメントがさらに重要になる
上で説明した通り、自分のソースコードですら理解するために読むことがあります。
チームで開発しているときには、他の人のソースコードを読むことが増えます。逆も同じで、自分が書いたソースコードを他の人が読むことも。
自分で書いたときと同じように、ソースコードを読んで理解すれば問題ありません。
しかし、ひとりのときと違い、ソースコードを読む時間はチームのメンバー分だけ増えることになります。
例えば、コメントを読めば10秒で理解できるところ、コメントを忘れたために1分かかったとしましょう。ひとりのときは50秒のムダですみますが、5人のチームだったら200秒のムダになります。
さらに、開発が完了したあとに保守をする人もいますから、最終的に何人の人がソースコードを読むか分かりません。
コメントを書くとチーム全体としてムダな時間が減りますので、コメントを書きましょう！
読み手のためにプログラミング時にはコメントを書こう
プログラミングをするときには、自分の書いたソースコードが（自分も含めた）多くの人に読まれる可能性があることを意識してコメントを残しましょう。
そして、コメントするときに気をつける点は次の3点です。
- コメントするべきで「ない」ことを知る
- コードを書いている時の自分の考えを記録する
- 読み手の立場になって何が必要になるかを考える
