【コーディング】できるエンジニアはコメントにWhyを書く

こんな経験をしたことはありませんか？

プログラミングを行うとコード中にコメントを書くことがありますが、コメントの書き方でプログラマーのスキルが分かります。

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

もし、コメントに「処理の内容」を書いているとしたら、エンジニアとしては無能かもしれません。

対象読者

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

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

結論から言うと、有能な人はコード中のコメントに「Why（なぜ）」を残します。

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

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

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

なぜなら「理由」や「目的」、「背景」はコードから読み取れないからです。

コードを読めばプログラムがどう処理するかは分かります。
極論を言えば、分からないことはないはずです（読みにくいとかはあるかもしれませんが）。

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

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

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

int main( void )
{
    int a = 0;

    a = func_a( 1, 10 );

    return 0;
}

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

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

int main( void )
{
    int a = 0;

    a = sum( 1, 10 );

    return 0;
}

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

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

たまに関数名を短くすることにこだわる人がいますが、可読性より優先すべき項目とは思えません。
無用とも思いませんが優先度は低いです。
分かりやすいのに短い命名が最高です。

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

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

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

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

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

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

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

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

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

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

コーディング時に意識しておきたいこと

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

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

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

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

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

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

リンク