【IT】Rubyコミッター・Yuguiに学ぶ、コードに書くべき「適切なコメント」と「適切な場所」

ノチラ ★

https://cdn-ak.f.st-hatena.com/images/fotolife/b/blog-media/20180508/20180508182455.jpg
プログラミングにおいて、どんな初心者でも書けるけれど、適切に書くのは上級者でないと難しいもの。それがコメント（=ソースコードに書かれている注釈やメモ）です。

不適切なコメントをつけても、プログラムの動作には影響しません。しかし、書き方の巧拙によって、コードの可読性や理解のしやすさには雲泥の差が出ます。良質なコメントが良質なコードをつくるのです。

今回はRubyコミッターでありgrpc-gatewayの開発者でもあるSupership株式会社の園田裕貴（Yugui）さんに、優れたエンジニアがどんな観点を持ち、どんなコメントを書いているのかを聞きました。

――園田さんはどんな箇所にコメントを書いているか教えてください。

園田：まず、外部との接点にはコメントを書くべきだと考えています。要するに、パッケージやモジュールなどの機能で、外から利用されることを想定しているもの。それが最初の候補です。

なぜかというと、プログラムがうまくモジュール化されているならば利用者はコードの内部を知る必要はないですが、呼び出すに当たり「どんな振る舞いをするのか」「何に気を付けるべきか」といった情報は知っておく必要があるからです。

例えば、引数が文字列型だとして「どんな形式の文字列であるべきなのか」までを言語仕様で制限できるものはそんなにないですよね。少なくとも、メインストリームで使われているプログラミング言語としてはすぐには思い当たりません。

パッケージやモジュールを外部から利用する人には、どんな形式の文字列を期待するのか情報提供しなければなりません。つまり、他者がそのコードを利用することを前提として、コードだけでは伝え切れない情報を付属的に伝える。これがコメントを書くべき箇所の基本的な考え方です。

――では、外部とのインターフェースには具体的に何を書くべきでしょうか？

園田：一般論として最初に検討するべき候補はあります。「（1）事前条件」「（2）事後条件」「（3）不変条件」「（4）入力の意味」「（5）出力の意味」「（6）副作用」「（7）計算量」です。要するに、利用する側が知っておくべきだけれど、コードの中身を見なければ容易には分からないものです。

ただ、究極的な答えはどうしてもケースバイケースになってしまいます。例えば、モジュール化のためにパッケージを分けてはいるけれども、そのパッケージを自分しか使わない確信があれば、コメントは書かなくていい。

だから、ライセンス（利用許諾）やチーム体制など「プログラムがどんな人にどう使われるのか」も、コメントを書く書かないの判断材料になってくると思います。

【コメントの技法2】どんな読者が読むのかを考える
――ソースコードの処理内部でコメントを記載する箇所の候補を挙げるとすれば？

園田：候補を検討するに当たり考慮すべきは「どんな読者がコメントを読むのか」です。読者がどんなスキルを持っていて、何を知っているのか。それを踏まえることが重要になります。

ここで言う想定読者とは、他のチームメンバーあるいは将来の自分です。その人たちに向けて「コードを日常的に読む人が知らなければいけない情報」を記載しておく必要があります。

――というと、具体的には？

園田：複雑なアルゴリズムにはコメントを書くべきでしょうね。ただ、どれだけ詳細に書くべきかはやはりケースバイケース。チームメンバーまたは自分自身の平均的なスキルレベルに依存すると思います。

例えば、私は以前あるプロジェクトでワーシャルフロイド法の実装が必要になり、コードを書いたことがあります。そのコメントに「ワーシャルフロイド法」と書き、Wikipediaへのリンクを貼りました。

なぜなら、私はそれほど競技プログラミングには強くないからです。半年後くらいに自分がそのコードを見たとき、何のアルゴリズムか一目では判別できない可能性があるだろうと考えました。

でも、競技プログラミングに強いメンバーがたくさんいる会社もありますよね。そういったエンジニアならばコードを見ればワーシャルフロイド法だと分かります。だから書く必要はないでしょう。

https://employment.en-japan.com/engineerhub/entry/2018/05/22/110000