リーダブルコードをリーダブルにするぞ（その2）

はじめに

こんにちは
リーダブルコードの社内向け輪読会の資料です。
以下記事の続きです。

今回は4~6章をやります。

第4章 美しさ

この章で言う「美しさ」はロジックの美しさでなく、見た目の美しさの話です。
改行位置を周りと同じにしたり、インデントをそろえたりといった部分は、フォーマッタをチームで導入すればすぐ解決されるでしょう。
PythonであればBlack、TypeScriptやJavaScriptであればESLintの導入で解決できそうです。
フォーマッタの選定は世の中の主流のフォーマッタの流れに乗ってしまうのが良いと思っています。

ただ、

1. メソッドを使った整列
2. コードを段落に分ける

についてはフォーマッタのみでは解決できなさそうですね。
この辺はレビューで指摘していきましょう。

第5章 コメントすべきことを知る

コメントについてはコードで理解できる部分についてはコメントはする必要がありません。
例えば以下のコードにおけるコメントはただのメソッド名の和訳になっています。

# 入力されたフォーマットが正しいか確認するメソッド
def checkStrFormat(text):
   ...

リーダブルコードの今までの章で、メソッド名や変数名については多少名称が長くなっても情報を入れるべきだと書かれており、コメントは最終手段だと意識するべきです。
(この章でも言及していますが、メソッド名がわかりづらいものであればコメントするよりメソッド名を変更すべきです)

上記のコード例の場合、”なぜ入力された文字列をフォーマットしなければならないのか”をコメントしたほうがよさそうです。
この時、何をコメントすればよいか悩んだら、この章に書かれている通り、監督のコメンタリーのように何を考えていたかをとりあえず書いてしまうとよさそうですね。
コメントはなるべくしないほうが良いと上で書きましたが、とりあえず書いてレビュアーに見せる、あるいは明日の自分に見せる、のようなコメントを書くのは良いことです。
何か書いた後に削るような考え方のほうが結果的に適格なコメントが残せそうです。

第6章 コメントは正確で簡潔に

この章は具体例が多く、「コメントは領域に対する情報の比率が高くなければならない」を実際どうすればよいのか、を書いています。

6.5 入出力のコーナーケースに実例を扱う

コメントに困ったとき、監督のコメンタリーのようにコメントを書く、といった話が出てきましたが、さらにこちらの書き方のほうが意図を漏れなく伝えられそうです。
コードレビューがあるならば、とりあえず入力と出力と意図を書いて、どういったコメントを書けばよいのかレビュアーと相談する、といったこともありかなと思います。

6.7 「名前付き引数」コメント

インラインコメントが使えない言語において、以下のような形でメソッドの引数の説明を追加できる

Connect(/*timeout_ms=*/10, /*use_encryption=*/false)

確かにこのような書き方はできそうですが、あまり見たことないですね(Javaをあまり書かないからかもしれません)
行は長くなりますが、インデントをうまく使えば読みやすくなりそうです。

6.8 情報密度の高い言葉を使う

ただ一言「キャッシュ」といえばよいことだけを回りくどく書いてしまうのは個人的にやりがち。
ただ、例で挙げている言葉がわかりづらいので解説します。

• ヒューリスティック: 経験則
• ブルートフォース: 総当たり
• ナイーブソリューション: 単純な方法、実行結果は正しいが、あまり効率は良くない方法

これら言葉はコードに入れるのであればチーム内で合意はとったほうが良いかもしれません。

おわりに

今回もリーダブルにできましたね。
次回もリーダブルにしていきましょう。

参考文献

• リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック p.41～78
  URL：https://www.oreilly.co.jp/books/9784873115658/