ソース内にコメントを残しておくことの重要性について

システムを動かしているのは、各種プログラミング言語で書かれたソースコードですが、そのソースコード内には、実処理には影響しないコメントも含まれているのが一般的。

プログラミングを習い始めると同時に、コメントについても学ぶかと思いますが、特段コメントを書かなくても実処理には何の問題もないため、ついつい面倒な気持ちからコメントを省略してしまうプログラマーもいます。

しかしコメントのないソースコードは、”多くの人”は悪いものと考えます。今回はソース内にコメントを残しておくことの重要性について、ご説明していきます。

コメントを残すことで生まれるメリット

他人に引き継いだ際に処理内容が理解しやすくなる

趣味としてソースコードを書いてるアマチュアプログラマーであれば別ですが、仕事としてのコーディング作業となると、多くの人が一つのソースコードを共有することになります。

自分の担当しているプログラムも、いつかは別のプログラマーにバトンタッチする可能性は大いにありますし、共通部品のようなモジュールであれば、なおさら多くの人に影響を与えます。

コーディング規約などで、一定のルールに従って書かれているソースコードも、プログラマーの”クセのようなもの”が出るものです。そのため処理を実行して同じ結果が返ってくるとしても、ソースコードの中身は書いた人によってさまざまです。

何が言いたいのかと言うと、人の書いたソースコードは非常に読みにくいのです。きっとプログラム経験者であれば、他人が書いたソースコードが難解すぎて、イラッとした経験は皆お持ちなのではないでしょうか。

処理ごとに逐一コメントで処理内容を残しておくことで、他人にプログラムを引き継いだ際にも、理解しやすいプログラムとなりますし、感謝もされることでしょう。

自分自身も処理内容を把握しやすくなる

ソースコード内の処理内容が理解しやすくなるというのは、他者だけではありません。ソースを書いている自分自身もプログラム全体の処理を把握しやすくなります。それはステップ数が多くなればなるほど効果的です。

もちろんソースを書いているのは自分自身なので、どんな処理を実装しているのかは把握していることでしょう。それでもステップ数の多いプログラムになると、数日かけてコーディング作業をすることになったり、他モジュールとの組み合わせが発生したりすると「この処理はどんなことをしていたっけ？」と再度ソースを読み解かなければならないときも出てきます。

そうした際にも、コメントが残してあれば、プログラム全体を理解するのが容易になります。

メンテナンスがしやすくなる

プログラミングとは「ただ動けばいい」ではなく、後々のメンテナンスのこともしっかりと考えながらコーディングしていかなければなりません。

機能追加やバグ対応など、リリース後に既存のプログラムに手を入れることも発生します。そうした状況下でもコメントがしっかりと残されていれば、修正箇所を見つけたり、修正による影響範囲を調べたりするにも、過去のソースをいちいち読み解く必要がなくなり、作業自体を楽に進めることができます。

結果、業務効率の改善につながる

自分の書いたプログラムであれ、他人が書いたプログラムであれ、コメントが残されていることで、業務効率の改善が見込めるのです。

人に優しく、良質なソースコードを書きたいと思ったら、しっかりとコメントを残すことを意識しながらコーディング作業を行いましょう。

コメントの質も大事です

より業務効率を高めたいのであれば、コメントの質にも気を配らなければなりません。

ここでは簡単にしかご説明しませんが、ソースを新規で起こす際には、変数の目的や、インプットとアウトプットデータについて、処理概要などの情報を盛り込むようにします。新規でなくソースの修正時に関しては、修正日時や担当者、修正内容の経緯などを記載しておきたいものです。
※修正時のコメント対応については「ソース修正時にコメント文に残しておきたい項目（参考例付き）」の記事を参照ください。

コメント不要論もある

冒頭では「コメントのないソースコードは、”多くの人”は悪いものと考える」と申しましたが、”多くの人”という言い方をしたのは、必ずしも全ての人がそうは思っていないからです。

一部ではコメントは不要という主張をする人もおります。しかしそれは何の理由もなくコメント不要と言っているわけではなく、コメントを残す必要がないくらいきれいなソースを書くことの必要性を説いているのです。

そうした美しくきれいなソースコードばかりになれば、コメントを書く時間すら省略できるので、ある意味、本来追求する理想の形なのかもしれません。

 

おわりに

上記ではコメント不要論も挙げましたが、コメントを残すことはプログラムの基本です。面倒だからという身勝手な理由でコメントをないがしろにしていると、作業効率も悪くなりますし、プログラマーとしての評価も悪くなる可能性があります。

コメントを残す意味を理解した上で、質の高いソースコードを書いていくようにしましょう。