リーダブルコードを読み直したのでまとめてみた

## はじめに
今年の４月で技術者４年目なりました松田尚也です。
とあることがきっかけで名著リーダブルコード(※1)を読み直す機会ができました。  
改めて読むといい本だなぁと思ったので、せっかくだし記事でも書こうか、と思って書いています。
名著なので、皆さんご存知とは思いますが、改めて読む先輩エンジニアのかたは**「そうだそうだ！」**とか**「それ違うYo!」**という視点で見てもらいつつ、まだ読まれていない方や、エンジニアなりたての方は、「ほえぇこういう考え方があるんだ」とか気にしながら見てもらえると幸いです。

リーダブルコードは大きく分けて４部構成になっています。  
1. （ロジックに関わらない）表面上の改善
2. 条件分岐やループ処理の改善
3. 大きい範囲のコードでの再構成
4. その他（テストコードと復習）

まとめてみると、あまりに長くなってしまったので、この４つのうち本記事では１部の名前に関わるところのみ、まとめます。

##  優れたコード
「優れたコード」とは「他人が理解**しやすい**コードである」それはつまり、「**他人が最短時間で理解できるように書かれたコード**」と書いてあります。  
私達が普段書いているソースコードは、自分**だけ**が読むソースを書いているのではなく、他人**も**読むものです。
ここで言う他人とは、プロジェクトでソースコードに携わるすべての人を指しており、並行してプログラミングしているチームのメンバーはもちろん、数カ月後の自分や、ソースコードの保守をする人、数カ月後にアサインされる人まで含まれています。  

もう少しイメージしやすい？ソースコード以外の*資料*で考えてみます。
打ち合わせの資料、プレゼンの資料、議事録をイメージすると「他人が最短時間で理解できるコード(資料)」が優れていることがイメージできるのではないでしょうか。  
数カ月後、何を書いているか分からない資料やメモは、目的を果たせてないことが多いです。
理解するのに他人に聞かないと分からなかったり、他の資料を参照して、さらに他の資料を読んだり、、  、となる資料は、読みづらく分かりにくいため、認識齟齬が起きる可能性が高いかと思います。
この認識齟齬はプログラミングでいう、「バグ」や「保守しにくいソースコード」で、意図しない挙動を行ったり、機能追加や変更を行うのに、時間がかかりすぎるコードと一緒です。  

それ故に、他人が最短時間で理解できるコードは優れていると言えるのではないでしょうか。  

##  名前に情報を詰め込む
突然ですが、ペンケースと言われたものの中に何が入っていると思いますか？
ボールペン、鉛筆、消しゴム...このあたりは違和感ないと思います。
ですが、ペンケースにお金を入れる人がいたとします。
そのペンケースを持っている人はお金が入っていると思いますが、他人が見た際にはお金が入っているとは思わないでしょう。
  
ペンケースという名前は、それ以上のこともそれ以下のことも本来は想定されていないのです。
自分だけの世界ではない以上、そのものがもつ「名前」は、他人と認識や理解を共有する上でとても大切なものです。
プログラミングの世界でも同じではないでしょうか。
変数名や関数名は、そのモノがもつ動作や名前を明確に表せるものでないと、勘違いをしてしまいます。
この勘違いが、「バグ」を生む原因になることがあるのです。

名前は**情報**なんです。 　
その情報を見て勘違いの起こる名前は良くない名前です。
私の理解だと、変数名や関数名に入れる名前は、**共通認識が持てるような言葉**であるべきと考えています。 　

ちょっと書籍の内容を意訳してますが、名前の大切さに改めて気づくことができれば幸いです。

## 抽象的な名前より具体的な名前
この本を読み直すまで私は、名前に抽象的で汎用性のある、気取った名前をつけがちでした。 　
前章の内容の通り、名前は、「ソースコードを読む人が共通認識を持てる名前である」必要があると考えています。 　
抽象的で汎用性がある名前というのは、誰もが共通の理解が持てる名前である可能性が低いです。

### 抽象的で汎用性のある名前をつけてしまった失敗談
私が、汎用性で抽象的な名前をつけてしまった際の失敗談を紹介します。
とあるサーバのテスト環境の構築を行った際の話です。
複数環境ある外部システム(テスト)環境を切り替えられるようにしてほしいとの依頼がありました。
![failed_system_related_modification_method.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/351271/349d0a23-e2eb-4b88-b806-213faba1ea20.png)

よく行われると思いますが、環境変数で外部システムの接続先を切り替えられるようにしまし、環境変数の名前を`environment`(環境)としました。  

この名前付けが失敗しました。
こうして文字にすると、「それはないよ」と自分でも思うんですが、、、、。
当時、私の頭の中では下記の図のように考えていました。
![failed_system_related_environment_group.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/351271/185cf3e1-9f55-3f52-8b5c-3186d0576718.png)


一つの環境変数ですべてのシステムを変更させようとした結果、分かりにくく、変更の行いにくい設計になってしまいました。 
上記の図では外部システムが２つのみになっていますが、実際は６システムほどありました。

具体的に発生した課題は以下の2つです。  

- 外部システムが複数あるが、システムごとに切り替えができないこと
- `環境`という名前だと、開発/本番のことをイメージする人が多く誤解につながった

最終的には、`environment`という名前ではなく、`API_URL`というより具体的な名前に変更し、この環境変数が何を表しているのか分かりやすい形になりました。

「これって設計じゃん」って思う方もいらっしゃるかもしれませんが、名前付けも一つの設計だと考えています。
「具体的な名称を名前としてつけるべきだ」と言う考え方があったら、「うん？これだと、勘違いする人いないかな。そもそも、設計悪くない？」って気づけたかもしれない？と思ったのでこれを例に出しました。
(ホントは、この変更をしようとした際にRejectくらったのと、enviromentではなくnode_envで行おうとしていたのですが、伝えたいことは一緒なので嘘つきました）

あまりに汎用性を持たせた名前にすると、上記のように達成したいことから逸脱する可能性が高くなると私は考えています。
故に抽象的な名前より、具体的な名前の方が誤解の生まれにくい名前であると考えています。

## 名前の長さ
プログラミング歴1年ぐらいでよくやっていたのが、具体的な名前をつけようとして、ついつい長くなり、かえって何を表しているか分かりにくくなっていました。

名前の長さは時と場合によってどうすればいいのかが結構変わってくるものだと考えているので、こういう考え方をすればいいよという自分の中の指標はないんですが、リーダブルコードに書いてあることは、以下の2点でした。

- スコープを意識した上での名前付けをすべき
- 名前を省略する際は、プロジェクト外の人も理解できるレベルで省略をすること

特に、名前を考えるとき、見る人が`どこまで`変数名を意識しないといけないのかが分かりやすいと良いです。
変数が有効な`範囲`を意識した上で名前を考えることが、  丁度良い名前の長さに繋がると考えています。

省略しすぎた結果、何を表しているのかわからない状態になったり、逆に、クラス名やオブジェクト名で表せているにもかかわらず、重複するような名前をつけてしまったり等が無いか意識し、確認することが丁度いい長さにするコツだと考えています。

## 誤解されない名前
ここは、かなりハウツーになっているので本を読んだ方が理解が早いと思うので省略します。

## まとめ
「リーダブルコード」の名前付けに関わるところをまとめました。  
やはり名著っていうだけあって、すごく分かりやすくいいこと書いてあるなと思いました。
久しぶりに読んでみるといろんな気付きがあったので、みなさんもぜひこの機会に読み直してみてください！

### ※1リーダブルコードとは
後輩に読んでもらいたい技術書ランキングとか、影響をうけた技術書ランキングとか、Amazonで技術本年間売上ランキングとかあらゆる技術書ランキングの上位にいる書籍。  
「優れたコードとはどういうものなのか」ということを考え方から実践方法まで書いてあります。  
読みづらい本が多いイメージのオライリーから出版されている本ですが、このリーダブルコードは、すごく読みやすくさらっと読めます。  
読んだことない人はぜひこの機会に読んでみてください。  
[オライリーリンク](https://www.oreilly.co.jp/books/9784873115658/)