1ヶ月でWebデザイン・プログラミングスキルをオーダーメイドのカリキュラムで学べるスクール、それがWebCamp。

子供の想像力を伸ばしアイデアを形にする小学生向けプログラミング教室「プロスタキッズ」

0からのRuby入門その16〜ソースコードにドキュメントを書く〜

Pocket

はじめに

あなたのプログラムはわかりやすいですか?

プログラムはわかりやすく書くことが重要です。

なぜなら、プログラムは作った後も幾度となく修正する可能性が高いからです。
その場限りのプログラムならやっつけで書いても構いませんが、長く使うプログラムなら後で後悔することになるでしょう。

プログラムをわかりやすくするためには、コメントを書くことが有効です。

この記事では、Ruby初心者の方向けに、Rubyでのコメントの書き方についてお伝えしていきます。

適切なコメントを書いて、わかりやすいプログラムに仕上げましょう。

そもそもコメントってなに?

コメントとは、プログラムを説明するための文字列のことをいいます。

ソースコード中に記述しますが、プログラムには基本的に影響を与えません。
なぜわざわざコメントを書くかというと、後からプログラムを読んだときにわかりやすくするためです。

プログラムは複数人で開発されることが多いため、他の人に自分の書いたコードの意図を伝えるためにコメントを記述します。
また、ひとりで開発する場合であっても、数週間後の自分のためにコメントを書くことは非常に有効です。

それでは、単一行コメントの書き方からみていきましょう。

単一行コメントを書く

単一行コメントは、これまでもサンプルコードで使っていたので、見覚えがあるでしょう。

Rubyでは、単一行コメントに「#(シャープ)」を使います。たとえば、次のように書きます。

例:

単一行コメントはとてもシンプルで、”#”以降の文字列がすべてコメントとして扱われます。
行の途中からでも問題ないため、例のようにプログラム行の後ろに説明を書くことも可能です。

次に、複数行コメントの書き方をみてみましょう。

複数行のコメントを書く

ときには、長い説明文を書きたいこともあります。

単一行コメントを使って、一行一行書くことも可能ですが、行ごとに”#”を書くのは面倒です。

そんなときは、次のように複数行コメントを使いましょう。

例:

複数行コメントは、「=begin」から「=end」までの間がすべてコメントとして扱われます。

長いコメントを書くときには、複数行コメントを使うとよいでしょう。

どんなコメントを書けばよいか?

初心者の方は、いざコメントを書こうと思っても、なにを書いたらよいか悩んでしまうかもしれません。

コメントを書く場所や頻度も重要です。基本的に、ソースコードを読めばわかるようなことを書く必要はありません。

冗長なコメントはムダです。
つまり、ソースコードからは読み取れないような情報をコメントに残せばよいということです。
たとえば、特殊な処理をしている場合に、なぜそれを行っているかということなどです。

コメントの活用方法

コメントは説明を記述するだけでなく、他の用途にも使えます。

それは、「コメントアウト」です。
コメントアウトは、プログラムの一部をコメントにして処理を行わないようにすることです。一時的にプログラム行を無効化するために使うとよいでしょう。

RDocでコメントをドキュメント化する

Rubyには、「RDoc」というコマンドラインツールが用意されています。

RDocは、ソースコードに書かれているコメントからHTMLドキュメントを生成するためのツールです。

クラスやメソッドなどを自動的に抽出して、コメントと合わせて出力してくれるため、大きな手間を掛けずにドキュメントを作成できます。
クラスやメソッドの前にコメントを書くだけなので、一度使ってみるとよいでしょう。

RDoc:https://github.com/ruby/rdoc

まとめ

コメントの書き方がお分かりになりましたか?

用途に合わせて、単一行コメントと複数行コメントを使い分けられるようにしましょう。

わかりやすいコメントを書くことが大切です。
しかし、もっとも重要なのは、コメントが必要ないくらいわかりやすいコードを書くことです。

わかりにくいコードを、がんばってコメントで説明するのは本末転倒です。

その場合は、コメントを書く前にコードを改善しましょう。

投稿者:プロスタ編集部

  • このエントリーをはてなブックマークに追加
  • follow us in feedly

初心者がプログラミングで挫折しない学習方法を無料動画で公開中。オンラインに特化したプログラミングスクール「TechAcademy(テックアカデミー)」が解説。

この記事が気に入ったら
いいね!しよう

プロスタの最新情報をお届けします

あわせて読みたい

関連記事

ページ上部へ戻る