shiodaifuku.io

コメントを書かない技術 - 現代プログラミング勉強会

この記事は、「現代プログラミング勉強会」と称して僕が社内向けの勉強会で話した内容を一般公開できるように再編集したものです。

現代プログラミング勉強会シリーズは全4回に分かれています。

勉強会のターゲットとしては、以下のようなエンジニアを想定しています。

  • 普段の業務ではレガシーなコードしか見る機会がない若手エンジニア
  • 一定のプログラミング経験があるものの、主にレガシーシステムの保守を担当しているエンジニア

たとえどんな姿をしていようとも、本番環境で稼働しているコードは価値のあるものです。 一方で、コーディングスタイルや設計思想に関して言えば、いまあるものを将来に渡って盲信しつづけるのは非常に危険です。 この勉強会は、現代のアプリケーションに要求される特性を学ぶことと、これまで培ってきたプログラミングの常識について学習棄却の機会となることを目的としています。

コメントを書かない技術

ソースコードコメント界にはさまざまな宗派があり、これに言及すると紛争の火種になることは理解していますが今日はあえて私見を述べます。 ここでは、書くべきコメントと書いてはいけないコメントについて解説します。

書くべきコメントを書くスキルを身につけるのは簡単ではありませんが、書いてはいけないコメントを書かないようにすることは比較的簡単です。 この記事を読んだ人は最低限不要なコメントを書かない技術を持って帰っていただければ幸いです。

書くべきコメント

設計原則やコーディングルールに従ったコードは、(その原則が妥当なものとして支持され続けている限りにおいては)コード単体から実装者の意図を汲み取ることはそれほど難しくありません。 一方で、原則を逸脱していたり、暗黙的になんらかの前提条件を仮定していたり、その時点では不確実な情報を判断基準として使用していたりするコードはそれが難しくなります。 このようなコードを修正するのは苦痛を伴う作業です。

こういったコードでは表現できない情報を残したいときにコメントを使います。 よいコメントとは、そのコードを将来修正しようとする人に向けて、修正に際して考慮・検討しなければいけない事項を説明するものであるといえます。

例えば、SOLIDの原則をはじめとする設計・アーキテクチャ上のルールを破るとき、 その理由を説明するためにコメントを使うのは良い方針です。

現代でも有益と考えられているプログラミングの原則やデザインパターン、アーキテクチャは過去の数多の人類が積み重ねた成功と失敗からエッセンスを抽出し、 それを厳しい批判の目に晒したあとでなお残ったベスト・プラクティスであり、先人の努力に最大限のリスペクトを払いつつ粛々と守るべきものです。 とはいえ、我々が業務で取り組む問題には当然ながら未解決問題も少なからず含まれており、そのすべてが過去の経験則でカバーしきれるものであるとは限りません。 極めて稀ではあると信じていますが、先人の残したアドバイスに従うことができないケースや、あるいは従うべきではないと判断するケースがないとは言い切れません。

そういった場面で役に立つのがコメントです。 コメントにはなぜルールや原則を守れないのか、あるいは守らない判断をしたのかを書き残しておきます。

リント・ツール、フォーマッタを適切に用いた上で、SOLIDの原則を遵守した品質の高いコードのなかに、突然ルール違反のコードが現れるとかなり悪目立ちします。 目立ちはするのですが、コードを見ただけではそうなっている理由がわかりません。 後になってなんとかしようと思う人が現れたときに、そのコードがどういう時代背景によって生まれたのかを知る方法はコメントしかありません。

それ以外の例を挙げるならば、開放閉鎖原則を守ったコードを書く際に「自分は将来こういう変更が加わることを想定してこのコードを書いた」みたいな、 コードを書いた時点では不確定だったが前提として利用した考えについてコメントをするといいと思います。 このようなコメントも、後でそのコメントが付されたコードを修正する必要が発生したときに、どのように修正するのが良いかといった指針を与えてくれるはずです。

書いてはいけないコメント

ソースコードの動作を説明しようとするコメントは効果がないどころか有害なので書くのをやめてください。 そして、コメントを書くために工数を割くのではなく、コメントのいらないソースコードを書くことに工数を費やしてください。 変数のスコープは可能な限り小さくし、長すぎる処理は関数に分割し、オブジェクトの命名に最新の注意を払ってください。 それでもなお複雑な業務ロジックはコメントで説明したところで簡単にはなりません。

我々エンジニアは厳密に言語仕様が定められているソースコードですら書くのに難儀しているわけです。 あなたが特別なトレーニングを受けたのでもない限り、より自由度の高い自然言語を用いて、時間を超えた第三者に現在のあなたが意図している内容を誤解なく伝えるコメントが書けると思い込むのは傲慢が過ぎるのではないでしょうか。 この事実を理解せず、己の言語能力を過信したエンジニアが書くコメントは良くて矛盾塊になります。

読む側にとっても、結局コメントとソースコードを二重で読むことになり、悪ければコメントに嘘が書かれていないかを検証する仕事まで押し付けることになります。 誰かがそのコメントを目にしている時点でソースコードを読む覚悟を決めている状態です。 そのような場合はソースコードを読んでもらいましょう。 そして、読むのが辛くないコードを書くようにしましょう。

まとめ

以上のようなポリシーでコメントが書かれていると、コメントが多いコードはそれだけ品質の不安定なコードといえます。 コメントは少ないほうがよいのです。

もちろんこれはコメントがなくても十分に理解しやすいコードが書かれていることが前提にあります。 すなわち、コメントを書かない技術とはコメントがなくても大丈夫な品質の高いコードを書く技術のことを指します。 品質の高いコードを普段から書いていれば、やむなくクソコードを書くときもそれを自覚することができます。 クソコードであることを自覚できるならば、そうなってしまった理由をコメントとして添えるのも難しくはないでしょう。

余談: コメントをベースにしたドキュメント

コメントからドキュメントを生成するようなプログラミング言語もあります。 そういったコメントを書くこと自体は否定しませんが、生成されたドキュメントをプロダクトの一環として公開するのでもなければあまりこだわって時間をかけなくてもよいのではないかと思います。 それはもうコメントの姿をしているだけのドキュメントなので、ここで取り上げた話と同列に扱うものではありません。

最新記事

  1. クソお世話になりました
  2. Cloud RunでgRPC streamingができるようになったので動かしてみたりした
  3. 2020年の執筆業まとめ
  4. アーキテクチャを設計する仕事とは
  5. 決済システムを設計するときに忘れてはならないたった1つの大切なこと