oshiro の日記

I love good unittest, low level programing and nice team

コメントの目的はコードの「意図」を理解してもらうこと

最近 Twitter 等でコメント論争がありましたので, 自分自身のコメント方の振り返りも兼ねて記事に起こしてみようと思いました.

本当は「コメントとはかく書くべきである!」みたいなことが言えればいいんですけど、私そこまでコメント力無いので基本的には『リーダブルコード』に沿って行く方針にしようかと思います.
『リーダブルコード』偉大ですからね.

需要があれば OSS とか使って『リーダブルコード』の読書会とか開催したいです.

本記事の目的は「コメントすべきこと」について一定の方針を打ち出すことです.


コメントはなぜ書くの

そもそもですがなぜコメントを書くのでしょうか?

コードの動作を説明するためであったり, オプションなどの Usage を知らせるためだったり, パブリックメソッドの使用条件や注意書きを知らせるためだったりするでしょう。

リーダブルコード的コメントの目的は以下の通り.

コメントの目的は、書き手の意図を読み手に知らせることである。(P.56)

つまりさっき上げたような目的は必要条件ではあるけれど十分条件ではないということです。

なぜ意図を知らせる必要があるのかについてもう少し掘り下げて考えてみます.
「意図を読み手に知らせる」ことは自分サイドの理由です. 立場を変えて私が読み手だった場合どういうことをコメントから読み取りたいんでしょう?

チーム開発の場合だと一見不必要な処理が行われていたりする時に「なんでこんな面倒なことしてんの???」となることがあります.
OSS を使う場合とかだと「どういう引数与えると意図した動きができるのか」や, 「特定の条件で使用すると著しくパフォーマンス落ちるよ」というワーニングが欲しかったりしますね.

コメントはフリースタイルなのでかくあるべき論は難しいですが. 章題に私なりに答えるとすると 読み手に納得感を与え, かつ書き手の想定通りの動きをしてもらうため になります.

コメントに書くべきでないこと

リーダブルコードでは下記3点についてコメントすべきではないこととされている.

  • コードからすぐにわかること
  • コメントのためのコメント
  • ひどい名前をサポートするためのコメント

コードからすぐにわかること

これはいわずもがなかと思います. 新しい情報を提供せず, 概要を表して理解の助けになるわけでもない価値のないコメントです.

// Car クラスの定義
class Car():
    // profit に値を設定する
    def setProfit():
        ...

コードからすぐにわかることをコメントに書かない(P.58)

コメントのためのコメント

これはもう説明するまでもないですね. SSIA とかって言いたい気持ちになります.

ひどい名前をサポートするためのコメント

関数名や変数名は自己文書化されているべきであり, その振る舞いはコメントで補助されるべきではありません. なんだか英語を翻訳した日本語みたいになりましたが, これ結構大事です.

ネーミングについて詳しいことはこの記事の中で議論することはしませんが, 例えば init_object という関数があったとしましょう. 一般的にこの関数に期待する振る舞いは, とあるオブジェクトの状態を初期化するということです. しかし下記のようにコメントされていたら。。。

# 新規に object を new して, 引数をメンバに割り当てる
def init_object():
    ...

おいおい, 確かに init してるけれどもさ... 違うやん...

この場合 init は厳密ではなく. 実質このコメントに表されている振る舞いは create です.

通常このような補助的コメントは書くべきではなく, 自己文書化された名前をつけるように工夫すべきです.

コメントに何を書くか

ざっくりいうと書き手の意図を読み手に知らせるために必要なことすべてです.
そのために何が必要なのかということなのですが, 正直筆者には明言できません.

言えることは書き手の意図を読み手に知らせる事はコメントに書くべきでないことに書いたこと以外は全て書くべきですが, 分かりやすさなどは個人によって基準が異なります.
無駄なものは逆に読みにくくするので書くべきでないことをまず把握すべきですし, 逆にそれ以外のものは書いた方がよいコメントだと言えるのではないでしょうか.

自分のコメントスタイルを見つけてみてそこから試行錯誤してみて, できる限り色々な人に意見を求めるのがよいと思います.

「とりあえず実装したけど. もっとパフォーマンスの良い実装があるはずなので高速化を行う」であったり, 「とりあえず import できる形式として csv だけ作ったけどその内 xlsx 形式に対応して欲しいって言われるだろうから要対応」をコメントしておくのも他者が見た際にそのためにこんな実装になっているのかということを理解してくれるでしょう.

具体的な話にはあまり言及しませんでしたが, 特にチーム開発においてはコメントも一種のドキュメンテーションなので, チームのルールを統一することが大事かと思います.

まとめ

何が言いたかったのかというと, コードにはコードの役割があって, コメントにはコメントの役割があることです.
コードで全てを表現することはほぼ無理だと思いますし. よしんば可能だったとしてもそのために 100 のコストがかかるのであれば 10 のコストでコメントに残すべきです. 読み手が理解しやすいコードを書くことがなによりも重要ですし, そのために上手にコメントを活用していきましょう.

ちなみに python には docstring という機能もあるので活用するとコメントが書きやすくなります.

お付き合いいただきありがとうございました.
間違いのご指摘やご意見等ございましたら気軽にコメントください.

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)