プログラミングの「コメント」とは？書くときのポイント5つや参考書も紹介

プログラミングの学習をしていると、プログラミングのコメントを書く機会がたくさんありますよね。

プログラミングのコメントは知っていても、

などについては、正直よくわからない方が多いのではないでしょうか？

そこでこの記事ではコメントの書き方のポイントなどについて、初心者にもわかりやすいようにくわしく解説していきます。
エンジニアとしてステップアップしたい方はぜひ最後まで読み進めてくださいね。

プログラミングの「コメント」とは？

プログラミングのコメントとは、「ソースコード内に書かれているメモ」のことです。

コトバンクでは、以下のように説明しています。

ソースコードに記述する文章のこと。注釈、リマークとも呼ばれる。処理の内容や開発者の覚書などを記述しておくことで、ソースコードがよりわかりやすいものとなる。言語によって、コメントとして解釈される記述形式が異なる。

(出典：コトバンク)

一見むずかしいソースコードでも、コメントを確認すれば処理内容がわかります。
コメントはあってもなくてもプログラミングの動作には関与しません。

企業によっては、チームでの作業をスムーズにするために厳密にコメントを記載することをルールにしている場合もあります。

また、プログラミングの言語によっても書き方が異なります。
たとえば、PHPのコメントなら以下のようになります。

---

「今の働き方に不満はあるけど、日々の業務が忙しくてゆっくり考える時間がない…」
そんな悩みを持つ方に向けて【DMM WEBCAMP】では無料のキャリア相談を実施しています。
ビデオ通話で相談をすることができるため、仕事で忙しい方でもスキマ時間に気軽にカウンセリングを受けることも可能です！
プロのキャリアカウンセラーと一緒に、今後のキャリアについて考えてみませんか？

プログラミングのコメントはいつ書くのか

プログラミングのコメントは、どのようなときに使用するのでしょうか？
ここでは基本的な2つの使い方についてご紹介していきます。

1.メモを残したいとき

コメント文をきちんと書いておけば、しばらく時間が経ってから見返しても内容がすぐにわかるのでとても便利です。

具体的には、

などをメモとして残しておくことが多いでしょう。

また、チームで開発を行う場合、プログラムを見るのは自分だけではありません。
自分が見返すためだけでなく、プログラムを見た第三者にとってもコメントは役立ちます。

2.コメントアウトしてデバックするとき

コードをコメントにして無効化にすることを「コメントアウト」といいます。

一部のコードをコメントアウトすれば、どこでエラーが起きているかがわかります。
そのため、デバックにも使用されるんですね。

また、プログラムを修正するときに、将来元に戻す可能性のあるコードをまるごとコメントして無効化する場合もあります。

言語別コメントの書き方3つ

プログラミングのコメントといっても、その書き方は言語によってそれぞれです。
ここからは、代表的な3つのプログラミング言語別の書き方をくわしく見ていきましょう！

1.Java・PHP・Cは「//」

「Java」「PHP」「C」は、基本的に「//」と書きます。

また、PHPは「#」をつけてコメントを書く場合もあります。

PHPの練習ができるおすすめ学習サイトに興味がある方は、こちらの記事もぜひご覧ください。

【初心者向け】PHPの練習ができる学習サイト11選！

2.Rerlは「#」

「Rerl」は、「#」を書きます。

3.Rubyは「=begin」と「=end」で囲む

Rubyは、「=begin」と「=end」で囲んで書きます。

Rubyの特徴や学習方法についてくわしく知りたい方は、こちらの記事もぜひ参考にしてください。

Rubyとは？3つの特徴や学びやすい理由を解説！メリットとデメリットも紹介

---

「今の働き方に不満はあるけど、日々の業務が忙しくてゆっくり考える時間がない…」
そんな悩みを持つ方に向けて【DMM WEBCAMP】では無料のキャリア相談を実施しています。
ビデオ通話で相談をすることができるため、仕事で忙しい方でもスキマ時間に気軽にカウンセリングを受けることも可能です！
プロのキャリアカウンセラーと一緒に、今後のキャリアについて考えてみませんか？

コメントを書くときのポイント5つ

コメントはどんなことでも書けばよいというわけではありません。
書き方によっては、コードの視認性が悪くなってしまう恐れもあります。

ではどのようなポイントに気をつけて書けばよいのでしょうか？
ここからは、コメントを書くときの5つのポイントをご紹介していきます。

それではさっそく見ていきましょう！

1.読み手のことを考えて書く

コメントは後から処理を見直したり、他の人がソースを読んだときにひと目で処理内容がわかるように書くことが大切です。

自分だけが理解できる書きかたではなく、誰が見てもわかりやすいように書きましょう。
ストレートではない曖昧な表現など、読み手に疑問が残る表現は避けるべきです。

2.コメントルールを決めておく

ルールを決めておけば、コメントを短くできるなどメリットが沢山あります。
チームで開発をするときはもちろん、自分1人だとしてもコメントルールを決めておきましょう。

一般的によく使われるコメントルールには以下のようなものがあります。

3.適切な名前をつける

これはプログラミングの基本ともいえますが、クラスやメソッドなどには適切な名前をつけましょう。

コード側で工夫できるのは、変数名でも同じです。
変数名を説明するためにコメントを書くのではなく、変数名を適切なものにすればコメントが不要になります。

できるだけコメントが必要ないきれいなコードを書くことも大切です。

完結でわかりやすいプログラミングのコードの書きかたについては、こちらの記事を参考にしてください。

プログラミングの読みやすいコードの書き方のコツ5つを解説！練習方法3選も紹介

4.シンプルに書く

コメントを書きすぎてしまうと、読みにくくなってしまいます。
大量のコメントではなく、少数の本当に優れたコメントを書くようにしましょう。

コードの処理内容をもう1度説明するようなコメントは不必要です。
たとえば、下記のようなコメントを見てみましょう。

上記のコメントは、コードを見れば解読できるような内容になっているため書かなくてもよい情報です。

5.見られて困る情報は書かない

コメントにした部分はWebブラウザには表示されないため、どんな情報も書きたくなるかもしれません。

しかし、そのページのソースコードを調べれば誰でも簡単にコメント部分を確認できます。
そのためパスワードなどの重要な情報は書かないようにしましょう。

コメントで書くべきではないこと5つ

コメントでは書くべきではないこともあります。
ご紹介するのは、以下の5つのポイントです。

それでは順番に見ていきましょう！

1.コードの再翻訳

基本的に、「何をしているコードなのか」はコメントとして残す必要はありません。
コードの再翻訳となるようなコメントは書かないようにしましょう。

たとえば、

などのコードを読めばすぐにわかるようなコメントは書かなくてもいいです。

2.コードを誰が書いたか

コードを誰が書いたのかは、コミットログを見ればすぐにわかります。
書かなくてもわかることは、コメントにする必要がありません。

3.コードをいつ書いたか

コードを書いた日付も、コミットログで確認できます。
不必要な情報はコメントにする必要がありません。

4.曖昧なコメント

コメントはできる限り曖昧さを排除する必要があります。
誰が見ても同じ解釈ができるコメントを書きましょう。

たとえば仮実装であれば「未実装」、削除予定であれば「非推奨」といったようにストレートな表現をすることが大切です。

5.情報が不足しているコメント

できるだけ読みやすい完結したコメントを書くことは大切です。

しかし、読み手にとって意外なコードを書くときなど、説明が必要な場合もあります。
このようなときには、読み手を混乱させないように説明をコメントとして残しておきましょう。

また、半年、1年、2年と、時が経てば、コードを書いた本人でさえ「どうしてこのプログラムを書いたのか？」と忘れてしまうこともあります。

未来の自分やメンバーを困らせないためにも、「なぜこのようなプログラムにしたのか？」をコメントとして書いておくことはとても大切です。

おすすめのコメント参考書2選

参考書から体系的に知識を身につけることも大切です。
そこでここからは、プログラミングのコメントへの理解を深めるためにおすすめの参考書を2冊ご紹介していきます。

エンジニアとしてのスキルアップのためにも、ぜひ読んでみてくださいね。

1.参考書リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック

「リーダブルコード」は、よりよいコードを書くためのノウハウが詰め込まれた1冊です。

本書では「コードは理解しやすくなければならない」というプログラミングの原則を日々のコーディングに当てはめる方法を解説。
コメントの書きかたや、名前の付けかたなどコーディングスキルを上げるための実践的な方法が学べます。

相手に伝わるコードやコメントの書く方法を学びたい方におすすめです。

2.Clean Code アジャイルソフトウェア達人の技

「Clean Code」は、読みやすい洗練されたコードを書くための方法が学べる技術書です。
本書を読めば、「なぜこのようにプログラムを作る必要があるのか」が理解できるでしょう。

コードの記述が多く、実践形式が見られるのも魅力的なポイント。
コードを書くすべての人に1度は読んでいただきたい1冊です。

まとめ：コメントはコードを理解しやすくするためのもの

コメントはただ処理の内容を記載するだけでなく、さまざまな用途で使います。
ただ何も考えずにコメントを書くのではなく、明確でシンプルな内容を書くようにしましょう。

ただし、コメントに書く必要がないものもあります。
「コードだけで意図を明確に表現する」など、コメント以外で表現する方法を考えることも大切です。

どうしてもコメントでしか表現できないもののみを書くことで、ソースコードがとても読みやすいものになります。
エンジニアとしてステップアップするためにも、よりよいコメントを書くようにしましょう。