【７月２週目】リーダブルコードを読んで【１〜６章】
第1章 理解しやすいコード
読みやすいコードとは「他人が読んで理解するのにかかる時間が短い」コードである。ここでいう他人とは、開発チームのメンバー、未来のメンバー、そして未来の自分である。まず、自分以外のメンバーがすぐに理解できるのはもちろんだが、今後入ってくるメンバーにも読みやすいコードを書く必要がある。これは、その開発チームのコード規約に慣れ親しんでいない、途中から参画したメンバーにも読めるくらい読みやすく書くということである。ある程度同じメンバーで開発をしていれば文脈が掴めるので、そのメンバーであれば読めるかもしれないが、途中で参加するメンバーは読めない可能性もあるのというが理由である。そして、「過去に自分が書いたコードが読めない！」なんてことも起こりうるので注意が必要。
実際、未経験からプログラミングを学習していた際に作ったポートフォリオのコードを今見返してみると「なんだこの変数名は？？」なんてことが結構あったりする。
第2章 名前に情報を詰め込む
名前は短く縮めた「コメント」
変数や関数などそれぞれがどんな振る舞いを持つのか、どんなデータが入るのかなどが伝わる名前を付けないといけない。コードを見る人に対するメッセージの役割を持っている。ただ、変数や関数などはある程度共通した以下のような原則が適用できる。
使ってはいけない単語
共通した原則の中には「明確な単語を使う」というものがある。ただ英単語を繋ぎ合わせればいいというものではなく、明確な意味を持つ単語を選ぶということ。決して意味が抽象的すぎて曖昧な単語は選んではいけない。例えば次のコードで
def get_items ・・・ end
と「get」という単語が使われているが、これは使うべきではない。なぜなら、このitemsはどこからgetするのかが明確でないからだ。データベースからとってくるのかクライアント側からなのかがわかりにくい。ではこれを次のように変えるとどうなるか。
def load_item ・・・ end
明確な命名ではないが、getをloadにしたことでサーバー側から読み込んでいることがわかるので、少し読みやすくなった。 このように単語ひとつ変えるだけで伝わりやすさがかなり変わってくるので、わかりずらい単語はなるべく避けるか、他の単語と組み合わせて意味がわかりやすいよう心がけたい。 こちらの記事を参考にすれば単語選びに使う時間が短縮されそう。ただし、チームでコード規約がある場合はそちらに沿って命名して行く方が良さそう。
より具体的に
先程のコードではitemsをどこからとってくるのかがわかるようになったが、肝心なitemsはどんなものかがわかりにくい。例えばブログのように記事を投稿するアプリケーションであればitemsの代わりにaritclesと命名することで記事を取ってきていることがわかる。
def load_articles ・・・ end
名前の長さはどうすればいいのか？
長い名前は覚えにくいし、コードが見づらくなる。かといって短くしすぎると意味がわからなくなってしまう。ではどうすれば良いかというと、スコープを考えれば良い。 例えば以下のようなメソッドの中のみで使われている変数の場合は短い単語でもいい。ただし、その変数が多くの箇所で使われてる場合は文字数を増やさないと理解しにくくなってしまう。
def load_articles article = Article.find(1) end
第3章 誤解されない名前
誤解されにくくするための単語選び
全章では情報量が少ないためにわかりにくい問題に対するアプローチを書いてきたが、この章では「どちらとも取れる意味で混乱する」問題に対してのアプローチを書いて行く。 単語によって様々な意味に取れるものが存在するので、読む人は「これはどっちの意味？」となってしまう。それぞれの意味が真逆の場合は重大なバグになりかねないのでしっかりと対策できるようにしていきたい。
限界値を含めるときはmaxやminを使う
limitという単語は「未満（限界値を含まない）」や「以下（限界値を含む）」という二つの意味で捉えることができるので、限界値を含めるときはなるべくmaxやminといった単語を使う 良いコードとは誤解されないコードであり、他人の書いたコードが意図をしっかり理解できることである。よく使われがちだけと曖昧な単語が意外に多い。全章でスコープの範囲によって使い分けることと似ているが、狭い範囲で使われている変数名を参考にして広い範囲で使う変数に応用するケースがあるので、特に広い範囲で使われる可能性のあるAPIのメソッド名などには注意したい。 名前を決めるときにはあえて反対意見を考えてみたり、書いた後に誤解されないかどうかを検討することで防ぐことができそうだ。コードを書いて満足してしまう自分には刺さる内容だった。
第4章 美しさ
ここからは見た目の美しいコードについて書いて行く。コードが美しくなければ、コードレビュー時やリファクタリング時に読む手間がかかってしまうので、重要な要素であると考えている。
一貫性のないコード
例えば次のコード
def apple ・・・ end def orange ・・・ end def grape ・・・ end
appleメソッドとorangeメソッドとの間には改行が一行あるのに対し、orangeメソッドとgrapeメソッドには改行がない。 このように規則性のない改行は見る人を混乱させる。たった一行改行がされていないだけで「なんでここ改行されてないんだろう」と考えなくても良いことに時間と思考を使ってしまう。 次のコードはどうだろう
def apple ・・・ end def orange ・・・ end // 〇〇を取得する def grape ・・・ end
コメントがついているところとついていないところがある。これに関しては「コメントを入れないとわかりにくい」からという意見があるので必ずしも美しくないと言えないが、もし上のメソッドが全て同じような振る舞いを持つメソッドだったとしたら、これもまた「なんでここはコメントがあるのだろう」となってしまうため無駄な時間と思考と使ってしまう。
これ以外にもネストのスペースがバラバラだったり、複数のパラメータを代入する場面において＝の位置がバラバラなどといったことが美しく見えなくなる要因になりえる。こういった問題は自動でフォーマットできるツールがIDEに用意されていたりもするので、そういったものを利用するもの一つの手段である。大事なのは直感的に見やすいかどうかである。
第5章 コメントするべきことを知る
メソッドの説明などに使われるコメントだが、不必要なコメントは邪魔でしかない。例えば以下のコードで
# 記事を取得する def load_article ・・・ end
メソッド名を読めばわかることをわざわざコメントで書いている。こんなコメントを書いたら「知ってるわ！」と誰もが思ってしまう。そもそもコメントを書かなければわからないものがある場合は、一度その名前がもっとわかりやすくできないかと考えて見る必要がある。コメントすべきは「なぜこのように書いたのか」や「不具合がある箇所」などであり、名前を見ればわかるコメントは書いてはいけない。
第6章 コメントは正確で簡潔に
名前と同じくコメントを読み手の立場になって考える必要がある。なぜならそれら二つに共通するのは「読み手に対するメッセージ」だから。名前やコメントをする目的は、読み手に情報を正しく伝えるということなのでただ闇雲にかければ良いというものではないことを忘れないようにしたい。 具体的には以下のような単語は使わないようにしたい。それ・これ・あれ
所感
この本を読んだ後今まで自分の書いたコードを見返してみると、本書の内容がグサグサ刺さるほど「読んで理解するのに時間がかかるコード」だと感じた。転職前にプログラミングを学習していた頃は基本的に読むのは自分だけだったが、転職し実務を行なっていくと必ず自分以外の人にコードを見てもらう機会が多くなり、それまでいかに他人が読んでもわかりやすいコードを書くことを意識してなかったと痛感する。特にコメントを無駄に書いていたり、変数名や関数名の命名がわかりにくかったのでここは重点的に改善し、理解してもらう時間を1秒でも減らしていきたい。
