プログラムのコメント行について考えてみる

皆さんこんにちは。

コンストラクションソリューション事業部で開発を担当している板橋です。

 

普段私はプログラムを書いたり、チームメンバーのプログラムをレビューしたりするのですが、そんな私がプログラムのコメント行についてちょっと書いてみたいと思います。

1.「3年後、他の人が読んだときに伝わるか」

これは、私がプログラムを書く時、他の人のコードをレビューするとき、新人教育をするときなど、常々お伝えしていることで、とても重要な事だと私自身が教えられ、感じていることです。

私たちは一般的にシステムエンジニア(SE)とかプログラマ(PG)といわれる職業なわけですが、有り体な言い方をすれば技術系サラリーマンなんです。ですので、会社の人事部門から辞令が出れば他の部署に異動になりますし、転勤だってあり得ます。もしかすると転職することだって十分ありますね。その時、「3年後に同じ人が同じシステムをずっと保守しているか?」というのが問題になってきます。

担当者が変わるときは当然、引継ぎ作業をするわけですが、その時にプログラムの全てを読みながら説明なんてできません。そして、システムの障害という私たちの最大の敵は、忘れた頃にいきなり現れ、我々を困らせるものです。(本当に忘れたころとか、忙しい時に出るんです)

そんな時に、読みやすいプログラムと読みにくいプログラムがあるのです。

読みにくいプログラムとは、この記事のように(!?)プログラムの文字がびっしりと記述され、一切のコメント(※1)のないプログラムだったりします。ディスプレイに表示されていて、それを眺めているのに、まるで頭に入ってこない感じです。(脳が拒否反応を示しているんですね、、、)

※1コメントとは、そのアルゴリズムがどのような仕組みで、どのように振る舞い、どんな結果を出すかを説明文として記述することのできるもので、大体の言語で記述することができます。

それに対して読みやすいプログラムというのは、適度に空白があり、プログラムを書いた人の考えがコメントして記述されています。

  • なぜそうなっているのか
  • どういう仕組みに基づくのか
  • どういう流れで目的の結果を得るのか

こういったことがコメントとして残っていると、非常に助かるのです。

ですが、実際の問題としてこのような有益なコメントをプログラム上で見ることはそれほど多くないのが実情です。逆に、プログラムを見ればわかるコメントは結構おおいですね(苦笑)

  • XXXを読み込みます
  • ***を実行します
  • ???をキャンセルします

など。これらはプログラムを見れは一目瞭然のケースが多いのであまり必要としないコメントです。本当に書いてほしいのは、どうして読み込むのか。どうして実行するのか。どうしてキャンセルするのか、、、などの理由というかプログラマの脳内で何を考えているのかを書いてほしいのです。

 

2.なぜ、そのようなプログラムを書いたのか

レビューをするときに、複雑なプログラムを見たときに私が最初にする質問です。”まずは”しっかりその理由聞きます。「ダメなコード書きやがって」みたいな気持ちで責めてませんよ(本当ですよ!)。これは質問なんです。

これだけ世の中がシステム化されている世の中ですが、そのシステムを作る我々の作業は手作業でプログラムを書いていきます。当然、ツールやライブラリ等を使って効率化できる部分はしっかりとやっていく訳ですが、それですべてが出来上がるわけではなく、どうしても最終的にはプログラマによる手組のプログラムが必要になります。

その時に、「ある結果を得るために複数の方法がある中、どうしてこの方法をとったのか」という事を確認します。だって、無意識の中でプログラムが出来上がるわけではないし、何か理由があるはずなんです。

その理由こそコメントに残してほしい内容であり、その後の担当者へ引き継がれていかなきゃいけない内容なんです。見ればわかるコメントなんて書かなくていい。ただ、なんでそう考えたのか。それをコメントに書きましょう。そういうコメントなら2,3行といわず、10行でも20行でもあっていいと思います。(私個人としては)

 

3.コメントは意外と文章力が問われる

そうなんです。上記では「理由を書けばいい」的な事を書きましたが、この文章みたいに(!?)ダラダラと書けば良い訳ではありません。

本当に書かなきゃいけないことを整理してみましょう。

  • どうして(仕様やユーザーからの要望による要因など)
  • 何が(トリガーとなるもの)
  • いつ(発動のきっかけは何か)
  • 何を(対象物は何か)
  • どうするのか(具体的な操作の内容)

これらの具体的な内容がコメントでしっかりと明記されていないといけません。

意外と、自分の脳内にあるイメージを言語化して文章にするのは難しく、日頃から心掛けていないとなかなか身に付かないものです。

ですが、こういった訓練は自身の会話スキルの向上にもつながりますので非常にお勧めです。

特にシステムエンジニアやプログラマには言葉による表現が苦手な方が多いですから、この記事を見た方は是非取り組んでみましょう。

 

 

今回は、コメントについて私の熱い思いを書かせて頂きました。

次の機会には、頑張って「やってみた」系の記事を書ければと思います。

以上、板橋でした。