nikkie-ftnextの日記

イベントレポートや読書メモを発信

読書ログ | 『リーダブルコード』5章・6章 〜再訪して感じたコメントに関する自分の考え方の変化〜

はじめに

銃を抜いたからには 命を懸けろよ、nikkieです。

ミノ駆動本 11章「コメント」を機にいくつかの本をあたっています。

前回は『Clean Code』編でした。
今回は『リーダブルコード』のコメントにまつわる章の読書ログを残します。

目次

新卒時代に読んだ『リーダブルコード』

新卒ソフトウェアエンジニアとして働き出した後、会社の推薦図書の一冊だったので読んだ『リーダブルコード』。
コードを理解するのにかかる時間を最短にするという考え方は、私のコードの書き方に大きな影響を与えています。

コメントについては2つの章で取り上げられています。

  • 5章　コメントすべきことを知る
  • 6章　コメントは正確で簡潔に

（さらに詳細な目次は上のオライリーさんページで見られます）

改めて読み返したところ、5章の印象が大きく変わり、私は驚きました。
新卒時代は5章を読んで「コメントを積極的に書くぞ！」と思ったのですが、改めて読むと（他書でのインプットと相まって）そのようには思えませんでした。

『リーダブルコード』におけるコメント

コメントの目的とは、コードの意図を読み手に理解してもらうことである。 (5.5)

この「意図」とは、コードの書き手の頭の中にある情報です。
その情報をコメントとして書くよう促す提案は、5章で繰り返しなされます。

  • 5.2　自分の考えを記録する
    • コードを書いているときの考えをコメンタリーのように残す提案
  • 5.3　読み手の立場になって考える
    • 例として要約コメント：処理のまとまりで要約したコメントを書く
    • コラムでは、WHATでもWHYでもHOWでも理解に役立つものは何でもいいから書こう
  • 5.4　ライターズブロックを乗り越える
    • 頭の中にある情報をまず書き出し、それから読み直してコメントを改善していく提案

「コメンタリー」や「まず書き出す」、それから「理解に役立つものは何でも書こう」、これらから『リーダブルコード』はコメントを書くことを推奨している立場という印象です。
なお、コメントのあるべきは、「5.1　コメントするべきでは「ない」こと」や「6章　コメントは正確で簡潔に」で説かれます。

一方で"「ひどいコード+優れたコメント」よりも「優れたコード」"という主張もある

「5.1　コメントするべきでは「ない」こと」では「ひどい名前はコメントをつけずに名前を変える」という話題で、次が紹介されます。

「優れたコード > ひどいコード + 優れたコメント」

コメントが必要な命名は名前自体を変えよう（それがコードの自己文書化にもつながる）と例が紹介されます。
ここは『リファクタリング』でいうCode Smellのコメント1について言及していると理解しました。

一方、この章自体はコメントを書くことを推奨する主張が多いです。
そのため、「ひどいコードに優れたコメントを加えるよりも優れたコードが勝る」という主張は、その重要性を読み取るのがなかなか難しいかもしれません。

要約コメント再考

5.3の「要約コメント」を例に挙げます。
要約コメントとは、関数の処理のまとまりにコメントし、関数の概要が把握できるようにする方法です。
これは「ひどいコードに優れたコメントを加える」ケースと思われるため、私はむしろ書きたくないです。

書籍にもただし書きがあります。

塊を関数に分割できるならそうしよう。前にも言ったけど、ひどいコードに優れたコメントをつけるよりも、優れたコードのほうがいい

ですが、関数分割の例はなく、ここには目が止まりにくいように思われます。

「要約コメント」は「関数の抽出」というリファクタリングテクニックの契機となるCode Smellと思われます2。
「関数の抽出」を常中させつつある私は「要約コメント」よりも「関数分割」を選択します。
ここはコメントの章ではありますが、「関数の抽出」による自己文書化例を紹介してほしかった3と感じます。

コメントではない解決策を考えたいと感じる事項も取り上げられている

『リーダブルコード』のコメントの章は「要約コメント」以外にも、今の私は採用しないと考える項目がありました（考え方は人それぞれだと思うので、採用する方もいて全然いいと思います）。
設計関連のインプットをする中で、新人時代から私の考えは変わったということですね。

  • 『Clean Code』のコメントは最小限という主張がかなりなじむ
  • 読み手の立場になってコメントしても、読まずに使うこともありえるのではないか
  • プロジェクトを熟知していない人の立場になって詳細にコメントをしても、現実的には全部読まれることはめったにないのではないか
  • こういったコードや設計でのアプローチをまず試し、どうしてもコメントせざるをえないところだけコメントとしたい
    • コメントを使うよりも、いまはコードや設計を磨く道を模索したい

『リーダブルコード』は広く知られる一冊

『リーダブルコード』は日本のエンジニアコミュニティではかなり認知されている本だと思います。
ミノ駆動本5もよく比較される6そうですし、読みやすいコードにまつわるLT会7に参加したこともあります。
直近では以下を見かけました。

IMO：（特にコメントに関しては）先のステージにも目を向けたい

このように存在感がある『リーダブルコード』ですが、コメントに限っては『リーダブルコード』の先のステージがありそうということに気付きました。
先のステージとは『Clean Code』や『リファクタリング』で垣間見える世界です。

新卒時代に初めて読んだとき、『リーダブルコード』の教えはどれも守るべきものと感じられました。
これは守破離の「守」の段階だったのだと思います。

その後コメントについて他の本でも考え方を知り、いまは自分の考えが形成されるようになりました。
これは守破離の「破」の段階に差し掛かっている8ということかなと思います。
コメントに関するさまざまな主張を検討した上で、『リーダブルコード』のコメントに関する主張のいくつかについては、より守りたいと感じる他書の主張が思い浮かぶようになったのです。

終わりに

ミノ駆動本をきっかけに、コメントについていくつかの技術書を参照しました。
「コメントに関して技術書の主張はバラツキがある」と感じ、今回はコメントを積極的に書くように伝えている印象の『リーダブルコード』を取り上げました。

新卒時代に読んだ『リーダブルコード』を改めて読むと、コメントについての主張は諸手を挙げて賛成とはならず、自身の変化を認識しました。
技術書は限りなくありますが、コメントについて代表的な本を確認し、現時点の自分の考えは大まかに確認できたように思われます。
なお、この記事はあくまで現時点のバックアップですので、さらに経験を重ねていった先に考えが大きく変わる可能性はありえます。
この先どんな世界に到達できるのか結構楽しみでもありますね。

P.S. ミノ駆動本_読書pyの予習

2/10(金)開催、ミノ駆動本_読書py事前準備の寄り道として、『リーダブルコード』のコメント関連章を読んだのでした〜

コメントに興味がある方のご参加お待ちしています。
短い章なのでさっと読めますよ〜

  1. 『リファクタリング』では「コメントを消臭剤として使わない」と説かれます↩
  2. 関数の抽出はVS Codeの操作と一緒にリファクタリングテクニックを紹介する登壇で取り上げています↩
  3. 「要約コメント」を身に着けても「関数の抽出」という覚え直しがすぐ先で発生するため、最初から「関数の抽出」を紹介するほうが私にはよさそうに思えます↩
  4. 例えばスマホやリモコンのように、内部の詳細が全く分からなくても正しく使えるようにカプセルにしたいと考えます。カプセル化の参考：カプセル化とは「カプセルにすること」である↩
  5. 変更容易性が認知されるべく、ミノ駆動本は10万部を目指しているそうです。そして『リーダブルコード』は10万部売れた書籍です。ref: https://speakerdeck.com/minodriven/e-ikododexue-bushe-ji-ru-men-deenziniaringufalsedang-tariqian-wobian-eru?slide=90↩
  6. ↩
  7. ラクスさん、開催ありがとうございました！ ↩
  8. Alistair Cockburnさんのインタビューの守破離の話を念頭に置いています。守は1つの技法をコピーした段階（『リーダブルコード』で知ったコメントの書き方をコピー）、破は技法を集める段階（他書でも「コメント」について知見を収集） ref: https://youtu.be/mn74ElzSSKo?t=270↩