【プログラミング初心者】コメントを書くとき知っておきたいこと

プログラミング言語を学ぶとき、「コメント」は最初に習う項目の一つだ。

エンジニアだけではなく、勉強を始めたばかりの方でも「コメントはプログラミングに関係しないメモだ」というのは知っているだろう。

しかし、コメントの書き方については知っていても、「コメントの正しい書き方」については考えたこともないという方もいるはずだ。

このページではコメントの書き方のポイントについてお伝えする。エンジニアの入り口に立つに当たり、参考にして欲しい。

1 コメントとは？
- 1.1 メモとして使う
- 1.2 コメントアウトしてデバッグする
2 コメントを書くときのポイント
3 参考書籍

コメントとは？

コメントとは、ソースコードに書かれているメモだ。コメントがあってもなくてもプログラミングの動作には影響がない。

例えば、Javaだと次のような表記になる。

public class Main {
     public static void main(String args[]) {
        //  「//」の後ろはコメント
     }
}

public class Main {

public static void main(String args[]) {

// 「//」の後ろはコメント

}

PHPだと下のページの通りだ。

【PHP入門者向け】1分でわかるPHPコメントアウトのやり方

コメントには基本的には次の２つの使い方がある。

メモとして使う

プログラミングをしているときはそのシステムのことを真剣に考えながらコードを書いているはずだ。たくさんの役に立つ情報が頭の中を渦まいている。

しかし、一旦そのシステムから離れて半年も経ってみよう。驚くほど何も覚えていないだろう。

時間が経ってからソースコードを見ると、「このときの自分は何を考えていたんだ？」と悩むことは、しょっちゅうある。これは明らかに時間の無駄だ。

忘却はよりよき前進を生む

というニーチェの名言があるが、プログラミングに関しては当てはまらない。

また、自分だけではなく他の人に仕事を引き継ぐときのことを想像してみよう。目の前のコード以外は何一つ情報が残っていないことになる。設計書は残っているかもしれないが、全体像すぎてなかなか役に立ちづらい。

だから、色々な注釈をつけておいて、プログラムコードを読みやすくするメモとしてコメントが使われる。

調査機関が調査したところによると「ソースコードの19%がコメント」らしい。少し多い気もするが、実際これくらいのコメント量はあるのだろう。

コメントアウトしてデバッグする

もうひとつは一部のコードをコメントにしてプログラミングとして動かなくしてしまうという使い方だ。

コードをコメントにして動かない状態にすることをコメントアウトという。

一部ずつコメントアウトすることによって、どこでエラーが起きているかがわかる。機能まるごとをコメントアウトして確認することもよくある。

このページでは、前者の「メモとして使うとき」のポイントをお伝えしていく。

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

では、どんなコメントを書けばよいか見ていこう。

しかし、「何を書くか考えるよりも、役立ちそうなことなんでもコメントしておけばいいんじゃないか？」というご意見もあるだろう。

ごもっともなご意見だ。

しかし、コメントの量が多くなればなるほど、その分ソースコードを読むのに時間がかかってしまう。また、コメントが多くなりすぎると、コードの視認性がとてもとても悪くなる。

親切で書いたつもりが、反対にコメントによって混乱することもしばしばだ。

だからこそ、コメントは必要十分量を書くべきだ。

何をしているか書いたコメントは基本いらない

コメントで一番よく見るのが、「何をしているコードなのか」を書いたコードだ。

例えば、「ここで画面に出力する」「値がnullだったら、エラー処理する」などのコメントは頻繁に目にする。

これらのコメントは必要なのだろうか？　

複雑な場合はともかくとして、大抵の場合、コードを読めばすぐにわかる。次のようなコメントは意味がない訳だ。

public class Main {
    public static void main(String args[]) {

        //カレンダーを生成
        Calendar cal = Calendar.getInstance();

        //フォーマットを設定して出力
        SimpleDateFormat sdf = new SimpleDateFormat("[1] y/M/d");
        System.out.println(sdf.format(cal.getTime()));

        //フォーマットを変更
        sdf.applyPattern("[2] yyyy/MM/dd");
        System.out.println(sdf.format(cal.getTime()));
     }
}

public class Main {

public static void main(String args[]) {

//カレンダーを生成

Calendar cal = Calendar.getInstance();

//フォーマットを設定して出力

SimpleDateFormat sdf = new SimpleDateFormat("[1] y/M/d");

System.out.println(sdf.format(cal.getTime()));

//フォーマットを変更

sdf.applyPattern("[2] yyyy/MM/dd");

System.out.println(sdf.format(cal.getTime()));

}

ソースコードをそのまま日本語に翻訳しているだけのコメントは役に立たないし、日本語もコードも読むことになるので手間が２倍に増える。

初心者の間は自分用のメモとして書いておいてもいいが、仕事現場では役に立ちにくいコメントだ。

なぜそのコードになったのかを書く

ソースコードを見た他の人が一番知りたいのは、そのコードになった「理由」だ。

例えば、どうみても面倒な処理を書いてあるとき、「なぜこのソースコードを選んだのか？」は書いている本人しかわからない。

//ここは回りくどい処理だが、●●だったため、あえてそうしている

//もっとよい書き方があったと思うが、時間の問題で修正はしていない

など、なぜこのソースコードの状態になっているのか？　という質問が来そうな部分に、先に回答を書いておくのが親切だ。

そうしないと、何か理由があるのでは？と勘ぐって、なかなか手が出せなくなってしまうからだ。

何をしているか「What」はソースコードを読めば多くの場合わかる。しかし、「Why」は読んでもわからないことが多い。

なるべく「Why」を書くようにしよう。ただし、複雑な場合は「What」を書いておくのも損はない。

わかっているダメな点を書いておく

自分が書いたコードにケチをつけるのは勇気がいることだが、忘れないウチにしっかりとメモしておいた方がいい。

// ここは無理やりなので修正

// 高速なアルゴリズムに変更が必要

// エラー処理がざっくりすぎる。分割が必要

など、書いておけば、時間ができたときに修正がしやすくなるし、次の人が見たときに修正してくれる可能性もある。

どうしてもシステム構築は時間との勝負になりがちだ。完璧にできればいいのだが、なかなか理想通りには行かない。

せめて、こういったコメントを残しておくことで、問題を「見える状態」しておくことだ。

やりそうな失敗を周知する

やりそうな失敗を周知することも大事だ。

MAX_CAPACITY_MB = 100;

と書いてあるときのことを想定しよう。

「150MBに容量を上げたい」というニーズが後から出てくる可能性がある。しかし、実はもともと100MBにしたかったわけではなく、サーバーサイドの問題で容量の上限値が100MBだったということもあるわけだ。

そういうときには、下記のようにコメントを書いておくことで、上限値を上げるには先にサーバーサイドを改良する必要があることがわかる。

// サーバーサイドの上限値 MAX_CAPACITY_MB = 100;

コメントのルールを作っておく

チームで開発を行うときは、コメントのルールを作っておくとやりやすい。

例えば、次のような記法がある。

TODO：　・・・後でやるタスク

FIXME：　・・・不具合がある

XXX：　　・・・大きな問題がある

などだ。

これらをチームが全員知っていれば、コメントは短くできるし、注意喚起もやりやすくなるだろう。

参考書籍

コメントに関しての勉強は下記の書籍がオススメだ。

リーダブルコードはプログラミング全般の「読みやすさ」についてまとめた良書だ。コメントの書き方にも言及がしており、非常に勉強になる内容も多い。

ぜひ、一読してみてほしい。

まとめ

コメントはプログラムではないが、同じくらい大切な成果物だ。

「なんとなく」ではなく、「他の人と未来の自分への思いやり」だと考えて、丁寧に書くようにしよう。

きっと、周りからも将来の自分からも感謝される日が来るはずだ。

【プログラミング初心者】コメントを書くとき知っておきたいこと