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

Rubyコミッター・園田裕貴(Yugui)さんが、長年の経験で体得したソースコードに書くべき「コメントの技法」を教えてくれました。

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

プログラミングにおいて、どんな初心者でも書けるけれど、適切に書くのは上級者でないと難しいもの。それがコメント(=ソースコードに書かれている注釈やメモ)です。

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

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

園田 裕貴(そのだ・ゆうき/1@yugui
書籍『初めてのRuby』(オライリージャパン)の執筆者であり、Rubyコミッタ。スケールアウト(現Supership)の初期中心メンバーの一人として活躍をした後、Google Japan、Gengoを経てSupershipに出戻り、全社横断的な業務改善に取り組んでいる。

【コメントの技法1】外部との接点に書く

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

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

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

2

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

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

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

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

##
    # Evaluates Jsonnet source.
    #
    # @param [String]  jsonnet  Jsonnet source string.
    #                  Must be encoded in an ASCII-compatible encoding.
    # @param [String]  filename filename of the source. Used in stacktrace.
    # @param [Boolean] multi    enables multi-mode
    # @return [String] a JSON representation of the evaluation result
    # @raise [EvaluationError] raised when the evaluation results an error.
    # @raise [UnsupportedEncodingError] raised when the encoding of jsonnet
    #        is not ASCII-compatible.
    # @note It is recommended to encode the source string in UTF-8 because
    #       Jsonnet expects it is ASCII-compatible, the result JSON string
    #       shall be UTF-{8,16,32} according to RFC 7159 thus the only
    #       intersection between the requirements is UTF-8.

yugui/ruby-jsonnetより引用。園田さんが挙げているような観点に基づき、コメントが記載されている

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

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

【コメントの技法2】どんな読者が読むのかを考える

――ソースコードの処理内部でコメントを記載する箇所の候補を挙げるとすれば?

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

3

yugui/ruby-jsonnetのメインの処理を担う各モジュール(ext/jsonnet配下にあるもの)には、詳細なコメントはあまり書かれていない。ソースコードを読む読者が「Rubyの拡張機能を開発できる」「モジュールが実現したい処理の概要を理解できる」というスキルを持っていることを前提としているためだ

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

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

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

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

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

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

【コメントの技法3】コミュニティの方針に合わせる

4

――プログラミング言語・フレームワークの開発コミュニティのように「スキルの高いエンジニアが集まることが前提」という場合、記載すべきコメントの量も必然的に減りますか?

園田:そうですね。大切なのは「読者がプロジェクトに何を期待しているのか」を考えることです。

――例えば?

園田:プロジェクトの特定の箇所で「A」という方針でコードが書かれているならば、読者は他の箇所でも「A」という方針が貫かれていることを期待します。プロジェクト全体の一貫性を求めるわけです。

例えば、高いスキルや多くの知識を前提とするプロジェクトならば、最初から読者はその内容を勉強して参画するので、冗長なコメントは不要なはずです。にもかかわらず、くどいコメントがあると邪魔でしょう。頑張って書いても読者の害にしかならないのですから、書くべきではないですよね。

だから、どうコメントを書くべきかについてのもう1つの答えは、プロジェクトの一貫性を求めている読者のために「周り(コミュニティの方針)に合わせること」です。

5

ruby/ruby参照。Ruby言語のメインの処理を担う各モジュール(ext配下にあるもの)は、どのソースコードを読んでもコメントの書き方に一貫性が保たれている

【コメントの技法4】会社やチームの慣習に起因する内容を書く

――他にコメントを記載すべき箇所は?

エンジニアHubに会員登録すると
続きをお読みいただけます(無料)。
登録のメリット
  • すべての過去記事を読める
  • 過去のウェビナー動画を
    視聴できる
  • 企業やエージェントから
    スカウトが届く