コードコメントの書き方で書き手のレベルが分かる！コメントにはWhyを残せ！

プログラミングを行うとコード中にコメントを書くことがありますが、実は

そのコメントの内容でプログラマーのスキルが分かります。

こういうと「コメントなんかで分かる訳ない」という人が居そうですが、分かります。

少なくとも残念な人かどうかは分かります。本記事を読めばその意図が理解できると思います。

もし、コメントに「処理の説明」を書いているとしたら・・・

対象読者

・コメントの書き方に悩んでいる人
・むやみやたらとコメントを書いている人
・コーディングの上達を図りたい人

要旨：コメントには「Why（なぜ）」を残せ

コード中のコメントには「Why（なぜ）」を残します。

ここでいう「Why（なぜ）」とは、「なぜ、このコードを記述したか」です。

前後の処理から明らかに必要な場合など、いちいちすべての処理にコメントをつける必要はありません。

しかし、「なぜその機能が必要とされたのか」「なぜこのシグネチャにしたのか」など、人によって意見が異なったり受け取り方が異なる箇所にはコメントを記述するようにしましょう。

なぜなら「なぜ」だけはコードから読み取ることが出来ないからです。

コードを読めばプログラムがどう処理するかは分かります。可読性などは考慮せず極論を言えば、分からないことはないはずです。

つまり、処理の流れをコメントに書く必要はないのです。

ただし、コードを追えば分かるからといって、コメントを書かないだけでは非効率です。前提として、処理の流れが分かりやすいコードを書くことを意識しましょう。

例えば下記のようなコードより

int main( void )
{
    int a = 0;

    a = func_a( 1, 10 );
}

int func_a( int x, int y )
{
    return x + y;
}

下記のように関数に適切な命名をするだけで可読性は向上します。

int main( void )
{
    int a = 0;

    a = sum( 1, 10 );
}

int sum( int x, int y )
{
    return x + y;
}

大切なことは適切な命名を行うことです。

たまに関数名の長さにこだわる人がいますが、可読性より優先すべき項目とは思えません（無用とも思いませんが優先度は低い）。

はっきり言って読んでも理解できないコードは害悪です。

コードも悪ければ書き手も悪いと認識すべきです（そして改めるべき）。

しかし、読んでも理解できないコードは非常に多く生まれます。意外と思われるかもしれませんが、自分で作ったコードすら１か月、１年も経過すれば忘れてしまうのです。時間が経てば他人のコードになってしまいます。

だからこそ、自分が作るコードは誰が見ても分かるように書くべきなのです。

※既に出来上がっているコードが読めない場合は（　＾ω＾）・・・どんまいです

この観点も重要です。コメントはメンテナンスされません。

処理の説明を書いてしまうとコードとコメントで不整合を起こす可能性があります。

プログラムはコードの通りにしか動きませんので処理がどうなっているかは理解できます。しかし、メンテナンスされていないコメントが残っていると「コメントが正しいのではないか」という疑念が湧いてコードの妥当性に不安を抱く可能性があります。

そして、最終的にはコメントとコードのどちらが正しいのかを検証する羽目になり、無駄な工数が発生するのです。

「なぜ」のコメントはコードを書いた際の背景が書かれているだけなので、コードとの不整合ということがありません。言い換えると「要件」が書かれているので、処理が変わろうとも要件が変わらなければメンテナンスされなくても問題ありません。

ここまで述べたように、コメントの書き方・内容次第で有用な場合と、むしろ迷惑な場合があります。

初心者にありがちなことは

という理由でコメントを書くことです。

いずれも先を見据えていません。コメントはあれば良いものではないですし、処理の説明はコードですべきです。

コメントの重要性が理解できて初めて「脱初心者」だと思います。

そして、コードとコメントの両輪が整えられてこそ”一流プログラマ”でしょう。

リンク