この記事はスターフェスティバル Advent Calendar 2023 9 日目の記事です。

最近社内で可読性について会話をするタイミングがあり、可読性について思っていることを言語化してみるか〜と思ったので書いてみます。可読性って難しいしよくわからないよね〜

この記事では、可読性という単語をコードの把握しやすさといった認知負荷的な意味だったり誤読しにくさみたいな意味で使っています。

メンタルモデルに起因するものなのか、そうではないのかを意識する

メンタルモデル?

メンタルモデルというものは「XXとはこういうもの」や「こうしたらこうなるはず」のような人それぞれが持つ思い込みみたいなものだと理解しています。

コードを読んで理解するときのメンタルモデルは、これまでのプログラミングに関する経験や知識、そのロジックが解こうとしている問題についての理解、自然言語自体の理解などの積み重ねで作られていくものかと思います。

たとえば、僕は getName というメソッドを見たときに

状態の更新は起こらないだろうな
I/Oは発生しないだろうな
計算コストは低いだろうな

みたいに思ったりしますが、僕とは違うメンタルモデルを構築している人であれば「小さなロジックとかもなく、インスタンスプロパティをそのまま返しているだけだろうな」といったことまで期待するかもしれません。

メンタルモデルに起因する指摘は難しい

読み手のメンタルモデルと実際にコードに乖離があると読み手は読みにくいなとか理解しにくいなとか思い始めますが、残念ながらメンタルモデルは人によって異なり、ある人にとって可読性が上がる修正が別の人にとっては可読性を下げる修正になることがあります。

例えば関数指向になれている人は map や filter を使って配列を処理することは簡潔で読みやすく感じると思いますが、そうではない人にとっては for 文を使ってループ処理している方が読みやすく感じたりします。

そのため、自分にとって可読性が低いから変えてほしいという視点だけだと自分しか得をしない指摘になってしまったり、たいして実利を得ることができない議論のために時間を消費してしまったりするため、この可読性の低下はメンタルモデルに起因するものなのか、ロジックの複雑性に起因するものなのかなどを自覚することは大事だと思っています。

とはいえ、綺麗に区切れるものでもないと思うので難しいんですが

普通の範囲に収まっていそうであれば許容する

多くのエンジニアのメンタルモデルに概ね合致するようなコードを書くことは重要なため、 getName というメソッドで状態の更新を行うようなコードを指摘するのは有益だと思いますが、特別変なことをやっているわけではないコードに対してレビュアーとレビュイーが細かい点を主張しあうといった、お互いの普通あるいは常識をぶつけ合うだけで実利に結びつかないような議論は微妙だなと感じます。

（幸い自分の会社でそういった光景を見たことはないです

何を普通とするかは難しいためあくまで感覚的な話にはなってしまいますが、ある程度普通なコードに対しては nits くらいの温度感で意見を共有するに留めて、プロダクトのコード規約のアップデートなどに時間を使った方が有意義かなと思っています。