プログラミングの基本： 適切なコメントのすすめ

はじめに

hevo2.hatenablog.com

前回の記事では、繰り返しfor文を使って何度も同じ手順を繰り返すプログラムを作りました。

あらかじめ繰り返し回数がわかっている時には、for文を使うと楽にプログラムを書けます。

宿題の解答例

前回の記事の最後に出した宿題ですが、解いてみましたか？ ぜひチャレンジしてください。

• 「yuka1」プログラム
  • 「床ブロックを6歩先まで敷き詰めたら、そのまま時計回りにUターンして、床ブロックを6歩分敷き詰めながら戻ってくるプログラム」

今回はfor文の解説でした。次回は次のようなプログラムを作ります。実はこれまでの知識だけで十分作れますので、自分でもチャレンジしてみよう！#ComputerCraft #百億のマイクラと千億のタートル pic.twitter.com/M84CpZWOKw

— hevo2 and 🐢 (@hevohevo) 2019年9月22日

往復しながら床ブロック設置

-- 地面に置いたタートルでは床にブロック置けないので、浮かせる
turtle.up()

-- 床にブロックを敷き詰めながら6歩分前に進む
for i=1,6 do
  turtle.placeDown()
  turtle.forward()
end

-- 右の列に移動
turtle.turnRight()
turtle.forward()

-- 右の列のスタート地点に移動。こちら側を向いている。
turtle.turnRight()
turtle.forward()

-- 右の列に床ブロックを敷き詰めながら戻ってくる
for i=1,6 do
  turtle.placeDown()
  turtle.forward()
end

はい、出ました。新しい表現。行頭にマイナス2個つけた青字の日本語文章はなんやねん。

今回はプログラム中に書かれている「-- あいうえおかきくけこ」という表現に注目して詳しく説明しましょう。

プログラム中にコメントを書こう

プログラムを書いた当時はその内容についてよく知っていても、1ヶ月後に見直すと何を書いているのか理解するのに時間がかかることがあります。

また、自分の書いたプログラムを他人に見せる時に、何をやっているのかわかりやすいよう説明文章をつけるのはとても親切なことです。思いやり！

プログラム中にはコメント文章を埋め込むことができます。 積極的にコメントを書きましょう。

以下に例として、上記プログラムから該当部分を抜粋します。

-- 床にブロックを敷き詰めながら6歩分前に進む
for i=1,6 do
  turtle.placeDown()
  turtle.forward()
end

プログラミング言語Luaでは、行の先頭が「--」（マイナス2個）で始まる時にその行はコメント行とみなします。この行に書いた内容は人間用のコメントなのでコンピュータは解釈しません。遠慮せずにどんどんコメントを書きましょう。

また行の途中であっても、「--」を書いたら、それより後ろ側はコメントとみなされ、コンピュータからは無視されます。

コメントは最小限で良い。ただし良いコメントを書くこと

コメントをつけるのは他人のためであり、未来の自分のためでもあります。だからおおいにつけるべきです。 しかし、たくさんつければ良いというわけではありません。

今回私は、「for文がやっている手順の意味」を要約して短く説明するようなコメントをつけています。

このfor文自体は短いので、一つ一つの手順が何をやっているのかはすぐにわかりますよね。つまり、「下にブロック置く」「前に進む」「これらを6回繰り返す」という手順です。

ですから、次のようなコメントの付け方は冗長であり、はっきり言うと書くだけ無駄だと言えます。

-- 6回繰り返す
for i=1,6 do
  turtle.placeDown()  -- 下にブロック設置
  turtle.forward()  -- 前に進む
end

本当に重要なのは、「これらの手順によって結局何をしているのか」という「手順の要約」ではないでしょうか。これこそがプログラムを読み取るときに重要なことです。

プログラミング初心者にとって、「手順の要約」をプログラムから読み取るのはなかなか難しいことだと思います。

だからこそプログラミング初心者の方には、

• 「結局、何をしているの？」という自問自答を繰り返すこと、
• そしてその「手順の要約」コメントをプログラム中に積極的に書くこと

をオススメします。

初心者向けのコメントを書くコツ

これだけでは抽象的すぎてわかりづらいかもしれないので、例を示しましょう。

たとえばプログラミング初心者は、次のようなプログラムを書きがちです。

turtle.up()
for i=1,6 do
  turtle.placeDown()
  turtle.forward()
end
turtle.turnRight()
turtle.forward()
turtle.turnRight()
turtle.forward()
for i=1,6 do
  turtle.placeDown()
  turtle.forward()
end

まずは、空行を適切に入れて、個々の手順を意味のあるかたまりごとに分けましょう。

空行なしに比べれば、以下のように空行を入れて意味のあるかたまりごとに分けるだけでもだいぶ読みやすくなるものです。

turtle.up()

for i=1,6 do
  turtle.placeDown()
  turtle.forward()
end

turtle.turnRight()
turtle.forward()

turtle.turnRight()
turtle.forward()

for i=1,6 do
  turtle.placeDown()
  turtle.forward()
end

次に、それぞれの手順のかたまりで「結局、何をやっているのか」を要約して短く説明しましょう。このときに、その手順を行う理由があるならそれもついでに説明してあげましょう。

-- 地面に置いたタートルでは床にブロック置けないので、浮かせる
turtle.up()

-- 床にブロックを敷き詰めながら6歩分前に進む
for i=1,6 do
  turtle.placeDown()
  turtle.forward()
end

-- 右の列に移動
turtle.turnRight()
turtle.forward()

-- 右の列のスタート地点に移動。こちら側を向いている。
turtle.turnRight()
turtle.forward()

-- 右の列に床ブロックを敷き詰めながら戻ってくる
for i=1,6 do
  turtle.placeDown()
  turtle.forward()
end

たとえば、以下のようなコメントの書き方はダメですからね。無駄です。

-- 上に浮かせる
turtle.up() 

そんなの関数を見ればわかる。なんで浮かせる必要あるのさ！という未来の自分のツッコミ声が聞こえてきそうです。

「結局、何をやっているのか」という手順の要約をすると同時に、もしその手順に隠された（説明しないとすぐにはわからないような）理由があるならそれも要約に含めると良いでしょう。

-- 地面に置いたタートルでは床にブロック置けないので、浮かせる
turtle.up() 

そう。こんな感じにね。

最終的に、「結局、何をやっているのか」を要約するコメントだけを拾い読みしたら、プログラムの全体像が読み取れるようになっていると良いですね。

最初に出したプログラムから、コメント文だけを抽出してみましょう。

-- 地面に置いたタートルでは床にブロック置けないので、浮かせる

-- 床にブロックを敷き詰めながら6歩分前に進む

-- 右の列に移動

-- 右の列のスタート地点に移動。こちら側を向いている。

-- 右の列に床ブロックを敷き詰めながら戻ってくる

ほら、コメントを読むだけで、このプログラムの全体像がつかめませんか？

なお、プログラミング中級者ともなれば、個々の手順を眺めるだけで「結局、何をやっているか」すら自然と読み取れるようになります。そこまで行けば、「要約型コメント」ですら最小限ですむかもしれません。

ただしその場合でも、なぜそんなことをしているのかという「理由型コメント」は必要です。

• 初心者は「要約型コメント」「理由型コメント」を積極的に書くこと
• 中級者なら「要約型コメント」は最小限で良いが、「理由型コメント」は必須。

ごめんな。CCは日本語ダメなんだ

今回はこのように、適切なコメントを書く重要性について述べてきたわけですが・・・。

ごめんなさい。CCって英語圏のMODなんで、日本語対応してないんですよ。

だからCC使ってコメント書くときは、英語を使って書くか、あるいはむりやりローマ字で書くしかないんです。

「なるほど、プログラミングと同時に英語の勉強も一緒にできるよね！」

・・・ごめん。空元気です。こんな風に、必ずしもポジティブに考えられる人ばかりではないよね。

次回予告

CC単体では日本語は表示できませんし、日本語コメントをプログラム中に書くことはできません。しかし、他のソフトウェアを使ってプログラムを書けば、少なくとも日本語のコメントをかけるようになります。

他のソフトウェア・・・。そう。外部エディタの利用です。

次回は、この外部エディタを使ったプログラミングについて説明します。

外部エディタを使う利点は日本語以外にもたくさんあるので、本サイトでは、CCのエディタであるeditコマンドではなくて、外部エディタを使ったCCプログラミングをオススメしています。

ということで、次回をお楽しみに。