13年前にリーダブルコードの解説を書いた須藤です。リーダブルコードにもコメントの話がありますが、本に書いているケース以外でもコメントを書くことがあるので紹介します。
ちなみに、私はできるだけコメントを書きたくない派ですが、そんな私でもコメントを書いておいた方がよいという場面があるのです。まぁ、レビューすることが増えちゃって、自分でコメントを書くというより、コメント書いておいて、と言うことの方が多いんですが。。。
いつ削除してよいかを書く
一時しのぎのコードを書かないといけないことがあります。たとえば、依存ライブラリーに問題があり、依存ライブラリーに報告して修正した（みんなもアップストリームで直すんだよ！）けどまだ修正が含まれた依存ライブラリーがリリースされていないときです。この場合は手元のコードに一時しのぎのコードを書いて対処したりします。
このような場合は「いつこの一時しのぎのコードを削除してよいのか」をコメントで書きます。
例： https://github.com/apache/arrow/pull/45310#discussion_r1924494628
Could you add a comment that we can remove this workaround when we require aws-sdk-cpp 1.11.489 or later?
このようなコードは不要になったらすぐに消したいものです。（研鑽Rubyプログラミングでも機能削除がうれしいと書いているよね！）このようなコメントがないと、このようなコードを見るたびに消せるかな？と確認しなければいけません。このようなコメントがあれば、すぐに消せるかどうか判断できます。リーダブル！
どんなlintを無視しているかを書く
linterは機械的にいろいろチェックしてくれるので便利です。しかし、たまに誤検出することもあるので、そのようなチェックは個別に無視します。
多くの場合、チェックはたくさんあり、特定のチェックを無視するためにはどのチェックかを識別する必要があります。識別するためのIDを数値で振っているlintもあればヒューマンリーダブルな文字列で振っているlintもあります。
たとえば、Hadolintは数値でIDを振っているlintです。# hadolint ignore=DL3006とかで特定のチェックを無視できます。しかし、これだけだとどんなチェックを無視しているのかわからないのでコメントでどんなチェックかを書きます。コメントに書いておくと読んだ人が調べずに理解できます。リーダブル！
例： https://github.com/apache/arrow/pull/44804#discussion_r1906020457
Could you add a comment that explains what is DL3006? A link to https://github.com/hadolint/hadolint/wiki/DL3006 and the summary in the page ("Always tag the version of an image explicitly.") will be enough.
似たような話で、（lintではないですが）CMakeのポリシーも同じことをしています。CMakeのポリシーも数値でIDを振っているので、そのIDのポリシーがどんなポリシーなのかを簡単に説明するコメントを書きます。
あえてやっていないことを書く
「普通に考えるとここにこんなコードが必要だけど、それをやっちゃダメ！」というときには、「あえてやっていないんだよ！！！」というコメントを書きます。
たとえば、 https://github.com/groonga/groonga/commit/756f4c36987cd646a99adbaf88a2c9cb67e87b3e がそういうコメントです。これは、私が https://github.com/groonga/groonga/commit/3d0edc67bcc00969791b5fb9d5d6ab54156b74d3 で「あれ、ここにこんなコードがないのはバグじゃね？」と思って直したら実際には壊していたことがあったので追加したコメントです。一見すると「ないことが間違いじゃない？」と勘違いしてしまうところには「なぜここにはそんなコードがないか」というコメントを書きます。
まとめ
コメントを書かない派の私でもコメントを書くことがあるので、リーダブルコードには書いていないタイプのコメントを紹介しました。
リーダブルコードは出版から10年以上経っているのにまだ売れていてすごいですね。（なお、売れても私にお金は入ってきません。）RubyKaigi 2025の本屋さんにも置いてもらったので買ってくれた人たちにサインしました。サインをした人たちはだいたい2冊目・3冊目の人たちでした。
クリアコードはリーダブルコードをベースにした研修を提供しているので、新人研修とかでやって欲しいとかあればコードリーダー育成支援サービスをどうぞ。
