プログラミングには「コメント」というものがあります。
コメントは、「プログラムに影響を与えない文字」のことです。
つまり、コメントはあってもなくても、実際のプログラムには何の影響も与えない存在なのです。
「プログラムに影響がないなら書く必要ないじゃん！」
そんなことを思う方もいるでしょうが、実はコメントを残したいタイミングというものがあるのです。
- コードに対するメモを残したいとき
- 一時的にコードを無効にしたいとき
ただ、ここで１点気を付けなければいけないことは、コメントを書き過ぎないこと。
これは特に、プログラミングを始めたばかりの初心者の方に多いです。
コメントは誰でも簡単に書くことができるため、「あってもなくてもいいようなコメント」をたくさん残してしまいがち。
コメントがたくさんあるとコードの邪魔になり、良かれと思って残したメモが「逆にコードをわかりづらくさせてしまう」なんていうのはよくある話です。
大切なのは、自分の中で「コメントを使うためのしっかりとした基準」を持っておくこと。
この「基準」を持っているかどうかが、綺麗で読みやすいプログラムを書くうえで重要になってきます。
今回は、そんなコメントの「書き方」や「基準」について詳しく解説していきます！
もくじ
プログラミングにおけるコメントの書き方
コメントの書き方は、プログラミング言語によっても違いますが、構成はほとんど同じです。
メモしたい行の先頭に記号をつけたり、無効化したいコードを記号で囲うことで、「コメント」として扱われるようになります。
では、さっそくコメントの具体的な書き方をいくつか見ていきましょう。
C、Java、PHPにおけるコメントの書き方
まずは、「C」「Java」「PHP」のコメントの書き方です。
// この一行がコメント/* この複数行をまとめてコメント この複数行をまとめてコメント */
「//（スラッシュ２つ）」以降がコメントになります。
これはあくまで「//」がついている行のみが対象です。
複数行をまとめてコメントにしたいときは、「/*」を「*/」を使って対象のコードを囲む必要があります。
Rerlにおけるコメントの書き方
次に、「Perl」のコメントの書き方です。
# この一行がコメント=comment この複数行をまとめてコメント この複数行をまとめてコメント =cut
「#」がついている行がコメントになります。
複数行をコメントにするときは、「=comment」と「=cut」で無効化したいコードを囲います。
Rubyにおけるコメントの書き方
最後は、「Ruby」のコメントの書き方です。
# この一行がコメント=begin この複数行をまとめてコメント この複数行をまとめてコメント =end
Perlと似ていますが、複数行をコメントにする書き方に少し違いがあります。
複数行をコメントにするときは、「=begin」と「=end」を使ってコードを囲まなければなりません。
【Ruby入門】プログラミング独学勉強法とRails環境構築【学習ステップ】 「コメントアウト」と「アンコメント」
プログラミングをしていると、コードを一時的に無効化したい場合があります。
たとえば、以下のような場合です。
- 機能を作るためプログラミングしたのはいいけど、いますぐは使わないとき
- デバッグする際に、一時的に関係ないコードを無効化して見やすくしたいとき
このように、一時的にコメントを使ってコードを無効化することを「コメントアウト」といいます。
これとは逆に、コメントを外して元のコードに戻すことを「アンコメント」といいます。
たまに、「コメントアウトの反対はコメントインだと思ってた！」という方もいるので、いまのうちに正しい用語を覚えておきましょう！
コメントを書く「基準」や「コツ」
ここまでコメントの書き方について、詳しく説明してきました。
ですが、コメントは「基本的には書かないほうがいい」ということを覚えておいてください。
コメントをいつでも使えると考えていると、「ほかの誰が見ても読みやすいコード」を意識しなくなり、コメント頼りで読みづらいソースコードになってしまいます。
また、コードを修正するときにコメントの書き換えを忘れてしまうと、「嘘のコメント」が残り続けてしまい、多くのプログラマーを無駄に悩ませる原因となります。
基本的には、コメントがなくても読みやすいソースコードを心掛けることが大切です。
コメントを書く際に気にするべきポイントや、ちょっとしたコツについても見てみましょう！
コメントが必要？書かないことも大切！
さきほどもお伝えしましたが、コメントは「書かなくていいことがほとんど」です。
書いたコードに対して「コメントがあったほうが読みやすいだろう…」と、１つ１つ丁寧にコメントしている方もいるでしょう。
ですが、コメントがなくても読みやすいコードを書くことのほうが重要なんです。
「コメントがないと読めない！」なんてコードは、プログラム全体を複雑化させてしまいがちです。
また、コードの理解を助ける目的で書いたコメントであっても、コメント自体の数が多ければ必然と行数も増え、ソースコードが見づらくなってしまいます。
これでは本末転倒ですよね。
コメントを書くときは、本当にコメントが必要かどうかを考えてみましょう。
- コメントがなくてもコードを理解できるか考える
- コードが読みづらければ、まずはコードを書き換える（リファクタリング）
- それでもコードが複雑であれば、コードを要約できるようなコメントを書く
まずはコードを読みやすくし、「コードよりもコメントを読んだほうがあきらかに理解が早い！」と自信をもって思えた場合のみコメントを書きましょう。
ここで初心者に多い、悪いコメント例を１つ紹介します。
# ユーザー情報を取得する
get_user(1)
# ユーザー情報を取得する関数
def get_user(id)
処理
endこのようなコメントなら書かないほうがいいです。
コメントが無くても、関数名を見るだけで何をしているのか十分わかりますよね？
プログラミングの変数名や関数名のつけ方！もう命名規則に迷わない！コメントが見やすいか
コメントは見やすくなければいけません。
自分にしかわからない言葉を使っていないか？
まわりくどい表現になっていないか？
コメントは、常に読み手のことを考えて書くことが大切です。
格好つけて英語でコメントを書くより、わかりやすい日本語で書いたほうがいいのです。
もちろん、英語がわかる方に向けたコメントなら英語でもいいでしょう。
ですが、あきらかに日本人しか見ないようなプログラムに、わざわざ英語を使って読み手の負担を増やす必要はありませんよね。
TODOなどのメモを残したいとき
コメントはコードを説明する目的以外にも、メモなどに使う場合もあります。
「この箇所にあとで処理を追加する必要がある！」
「この処理はもう少し読みやすくしたほうがいい！」
こういった場合は忘れないように、ソースコード上に一時的にメモを残すのです。
メモを残す場合、それがメモだとわかりやすいようコメント記号のあとに「TODO」などと書くことが多いです。
# TODO: この関数をリファクタリングする
def get_user(id)
処理
endあくまで一時的なので、必要なコードを書いたあとはTODOコメントは消さなければいけません。
ずっとTODOが残っているような場合は問題だと思いましょう！
コメントアウトしたいとき
プログラムの調査や動作確認をする際に、一時的にコードをコメントアウトしたい場合があります。
# hoge(100, 200)
=begin
def hoge(a, b)
puts a * b
end
=end上のコードは、すべてコメントアウトされています。
コメントアウト自体は何も悪くないので、必要であればどんどん使いましょう！
ですが、調査やデバッグした際にコメントアウトしたコードが残り続けることは問題です。
コメントアウトは一時的に使うものであり、確認などが終わったタイミングでアンコメント、もしくは削除しなくてはなりません。
ですが実際には、メモの用途で使ったコメントアウトが残り続けているケースがたくさんあります。
他のプログラマーがこれを見ても、「何のために書いてあるのかはわからないけど、残しておいたほうがいいんだろうな…」と変な気を遣ってしまい、消されることなく永遠と残り続けるのです。
これは本当に無駄なコードなので、絶対に残さないようにしましょう！
さいごに
今回は、プログラミングにおける「コメント」について解説しました。
コメントも実は奥が深く、読みやすいコード（リーダブルコード）を書くためにはいくつかのテクニックが必要です。
コメントの使い方をしっかり理解し、より見やすいコードを書けるように心がけましょう！
また、コメントに限らず「リーダブルコードをもっとしっかり学びたい！」という方はこちらの本がおすすめです。
僕もこの本を読んで、リーダブルコードを学びました。
コメントを書く基準についてはもちろん、変数や関数の書き方から、見やすいコード関するすべてのことが書いてあります。
内容もとてもわかりやすく、読んだあとすぐに実践できるものばかりです。
この本を読み終えた当時の僕は、「もう迷わないでプログラミングできる！」と強く感じ、開発速度がグンと上がったことを覚えています。
これはおそらく、コーディングするたびに「どう書くことがベストなんだろう…」と悩んでいた時間がなくなったことが大きいです。
本自体も小さく薄いので持ち運びやすく、電車の中でサッと読めるのも魅力的でした。
「コードを書くたびに、いつも迷いながら書いている」という人にこそ、読んで欲しい一冊です！
またね、キツネ（@kitaaaa_kitsune）でした！
【プログラミング入門】おすすめの基礎知識やプログラムの基本