本当は何を書くべき!?ソースコードコメントの意義とは？

　ソースコードを読む時、多くの場合はコメントが記載されています。コメントには「①ソースコードの処理の説明」、「②そのソースコードを書いた理由」、「③他のエンジニアに向けての注意」などがあり、書かれている内容は様々です。たとえば、それぞれ以下のような記載があります。

① //顧客情報を管理するオブジェクトを生成
② //本来はクラスを分けて作成すべきだが、時間が無いのでこのように書いている。要修正。
③ //ここは複雑な処理なので基盤チーム以外は修正禁止。どうしても修正が必要な場合は相談すること。

コメントは言語にかかわらず、ソースコードを読んだことがあれば一度は目にしたことがあると思います。ソースコードだけよりもコメントがあることで難しいコードも、その背景や意図を踏まえて理解しやすくなります。

1.コメントには何を書くべきか？
　実はソースコードのコメントに正解はありません。コメントを読む相手（自分向け、プロジェクトの他のエンジニア向け、不特定多数の人向け、など）によって書くべき内容は異なります。また、読む相手のプログラミングレベルによっても書くべき内容は違ってくるでしょうし、そもそもエンジニアの中には「コメントは不要」と考えている人さえいます。一番の目的は、「ソースコードの保守性を高めること」です。「何を書けば自分のコードの可読性は上がるか？」を考えてコメントする必要があります。

2.保守性を上げるためにいいコメントを書く工夫とは？
　いいコメントを書くためには事前の取り決めが重要です。プロジェクトや開発するソフトウェアに合わせてコメントの記載ルールを作っておくと良いでしょう。これはソースコードのコーディングルールと一緒に考えると、より良いものができます。「パッケージ・クラスはどのように分けるか？」、「どのようなテンプレートを使うか？」、「メソッドはどの粒度で記載するか？」などのコーディングの基準を作り、共通認識があることでどのようなコメントを書く必要があるかが見えてきます。たとえば、「クラスに持たせる責務は一つ」とコーディングルールで決めておいて、「クラスのコメントにはその責務を記載する」というコメントのルールを決めます。そうしておくことで、各クラスの責務をコメントで確認できるので、そのクラスがどのような処理を実行するのかを把握することができます。
　また、コメントのテンプレートを作っておくこともおすすめです。一般的に、コメントに書く情報量はエンジニアによって異なります。しかし、各ソースコードによってコメントに記載されている情報や粒度がバラバラだと、可読性の低いソースコードになってしまいます。テンプレートを作っておくことで、各コメントの情報や量を統一することができるので、見やすいソースコードを作ることができるようになります。

3.「コメント」の有効活用
　ソースコードにコメントする主な目的は保守性を高めることですが、それ以外の目的でも利用できます。たとえば、特定のコメントを検索できるようにしておくことがおすすめです。大規模なプロジェクトだとプログラミングは大人数で何日もかけて行います。うっかりソースコードを書きかけのまま放置してしまったということはよくありますが、コメントを活用することである程度この問題は防ぐことができます。まだ実装中や修正中のソースコードには「ToDo」や「FIXME」などと書いておくというルールを作ることで、対応中のコードを検索することができるので便利です。Eclipseのビュー機能を使えば、この仕組みは簡単に運用することができます。

4.書かない方がいいコメントとは？
　悪いコメントは挙げたらキリが無いでしょうが、特にプログラマーが書いてしまいがちなのは、コメントを必要以上に長く書いてしまうことです。たとえば、「ソースコードをそのまま翻訳したコメント」は多くのプログラマーが書いてしまいます。これは、ソースコードを読めばわかることなので書く必要はありません。本来ソフトウェアは「コメント」ではなく「ソースコード」に書かれている通りに動作するので、プログラマーはソースコードを読んでプログラムを理解します。コメントに多くの情報を記載することは、反対に可読性を落としてしまうので、必要な情報に絞ることが効果的です。

　今回は、ソースコードに書くコメントについて紹介しました。ソースコードコメントもプロジェクトを進めるための言わばコミュニケーションツールとしての役割を果たしているものの、ソースコード本来の機能とは違う使われ方であるとも言えます。その点を考えると、そもそもソースコードコメントがなくともプロジェクトが成立するように、事前に目的を正しく理解し、チーム内で認識を合わせて、円滑に進むように、コミュニケーションもまた整備していくことが重要であることは、こうしたコメントの意義とともに考える必要があるでしょう。