プログラミングの「コメント」とは?書くときのポイント5つや参考書も紹介 | WEBCAMP NAVI
【3月の受講枠も残りわずか】

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

プログラミング コメント

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

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

  • どういったときに使うのか?
  • 言語によってどう変化させればよいのか?
  • 上手く書くコツ

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

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

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

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

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

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

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

(出典:コトバンク)

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

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

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

PHPのコメント例
<?php

$str = ‘コメントのテストです’; //ここからコメント

echo $str;

?>

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

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

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

1.メモを残したいとき

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

具体的には、

  • いつ作成したのか
  • どのような処理をやっているのか

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

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

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

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

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

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

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

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

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

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

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

Java・PHP・Cのコメント

// 一行コメント

/*
複数行コメント
*/

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

PHPのコメント

# 一行コメント
// 一行コメント

/*
複数行コメント
*/

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

キーボードを打つ手 【初心者向け】PHPの練習ができる学習サイト11選!

2.Rerlは「#」

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

Rerlのコメント

# 一行コメント

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

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

Rubyのコメント

# 一行コメント

=begin
複数行コメント
=end

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

Rubyとはのアイキャッチ Rubyとは?3つの特徴や学びやすい理由を解説!メリットとデメリットも紹介

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

プログラミングコードを書くポイント

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

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

  1. 読み手のことを考えて書く
  2. コメントルールを決めておく
  3. 適切な名前をつける
  4. シンプルに書く
  5. 見られて困る情報は書かない

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

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

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

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

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

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

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

  • 「TODO」:後でやるタスク
  • 「FIXME」:不具合がある
  • 「XXX」:大きな問題がある

3.適切な名前をつける

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

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

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

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

プログラミング コードのアイキャッチ画像 プログラミングの読みやすいコードの書き方のコツ5つを解説!練習方法3選も紹介

4.シンプルに書く

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

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

NGコメント

php
<?php

// ファイル一覧を返す関数
function get_files($dirname)
{
// ディレクトリを開く
$dir = new DirectoryIterator($dirname);

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

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

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

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

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

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

  1. コードの再翻訳
  2. コードを誰が書いたか
  3. コードをいつ書いたか
  4. 曖昧なコメント
  5. 情報が不足しているコメント

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

1.コードの再翻訳

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

たとえば、

  • 「フォーマットを変更」
  • 「ここで画面に出力」
  • 「結果を出力」

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

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

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

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

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

4.曖昧なコメント

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

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

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

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

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

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

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

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

おすすめのプログラミングコメント参考書

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

  1. 参考書リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック
  2. Clean Code アジャイルソフトウェア達人の技

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

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

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

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

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

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

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

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

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

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

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

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

自宅にいながら、プロのキャリアアドバイザーに無料オンライン相談!

DMM WEBCAMPは転職成功率98%※1の全コースオンライン対応の転職保証型のプログラミングスクールです。短期間で確実にスキルを身につけて、ひとりひとりに寄り添った転職サポートで、未経験からのエンジニア転職を叶えます!

外出自粛期間中でも、自宅にいながらオンライン学習でスキルを高めることができます。

キャリアに迷ったら、まずはビデオ通話で無料キャリア相談を受けてみませんか?

自宅で過ごす時間が増えた今こそキャリアアップを目指しましょう!この機会を活用し、ぜひDMM  WEBCAMPの無料カウンセリングをご利用ください。

オンラインで実施中/
【無料】キャリア相談の日程を見る

※ 1 2020年4月時点