リーダブルコードから学んだこと【後編】

この記事は、[リーダブルコードから学んだこと【前編】](https://qiita.com/natsu0627pooh/items/9184b9b67944a4931ad5
)の続きです。

前編、後編のどちらを読んでも理解できる内容になっていますが、
興味があればぜひ前編も読んでいただけると嬉しいです。

## はじめに
こんにちは。エンジニアを目指す大学３年生です。

この記事では、プログラミング歴2年ちょっとの新人（私）が、
[リーダブルコード](https://amzn.asia/d/aklZpHj)を読んで気づいたことや学んだことを書き留めています。

あらためて、リーダブルコードは、真面目すぎず面白く、
「良いコードとはなにか」について分かりやすく述べた本だと思います。

一つの記事にまとめるとボリュームが大きくなりすぎるので、２つの記事に分けました。
この記事は後編です。

前編、後編を通して、以下の4つを扱います。

- 他人は未来の自分
- 誰が見ても処理がわかる命名をする
- コメントは、理解が早くなるように書く
- 理解しやすいコードは短い

今回は後編で、下2つを扱っています。

この記事が、
新しい気づきを得たり、知っていることを復習するきっかけになれば嬉しいです。

前編はこちら⏬
https://qiita.com/natsu0627pooh/items/9184b9b67944a4931ad5

## コメントは、理解が早くなるように書く
### 結論
コメントは、**他人がコードを理解するのを助けるためのもの**です。
多すぎても少なすぎてもわかりにくいコードとなってしまうので、
ちょうどよいコメントを書く必要があります。
### 詳細
コメントを書くべきコードは、以下のようなものがあります。
- 処理が複雑で、他人がコードを見たときに**直感的に理解できないコード**
- 他人が**疑問を持ちそうなコード**
- 他人に**考えていることを伝えたい**場合

ただし、他人はコメントを読むときも時間を使っているので、
**その時間で読めるコード以上の価値があるコメントを書く**必要があります。

一方、コメントを書くべきでないコードには、以下のようなものがあります。
- 処理が単純で、誰が見ても直感的に実装内容がわかるコード
- コード自体をシンプルにできる場合

コメントを書くべきでないコードは、ここに書いた内容で大体理解できそうなので、
コメントを書くべきコードについて詳しく述べます。

#### 直感的に理解できないコード
コードを見ただけではすぐに何をしているのか理解できないようなコードには、
コメントをつけることで理解の助けになります。

ただ、ここでいう「すぐに何をしているのか理解できないようなコード」は、
消して汚いコードというわけではなく、洗練されたコードのことを指します。

もし汚いコードなのであれば、まずはきれいなコードに直すことを優先します。

エンジニアは、
**優れたコード＞汚いコード＋優れたコメント**
というふうに考えているそうです。

#### 疑問を持ちそうなコード

他人が見たときに、疑問を持ちそうなコードにはコメントをつけるのが良いです。
例をあげます。
```py:example.py
image_quality = 0.72
```
例えば、上のようなコードを見て、なにか疑問を持ちませんか？
批判的にコードを見ている人は、
「何をどう考えて0.72にしたのか？もっと低くてはだめなのか？」
などと疑問を持ちそうです。

そこで、以下のようにコメントを付けます。
```py:comment-example.py
image_quality = 0.72 # 0.72 ならユーザはファイルサイズと品質の面で妥協できる
```
すると、読み手に値を決めた背景が伝わり、
数字の妥当性を確かめるなどという無駄な作業が減ります。

このように、他人が疑問を持ちそうなコードには、
その**疑問を解消できるようなコメントが書けると良い**です。

#### 考えていることを伝えたい場合

実装中、なにか気がかりなことがあったり、
他の人にも知っておいてほしいようなことがある場合にも、
コメントを書くことが望ましいです。

はじめは難しく考えすぎず、思ったことをそのまま書いてしまうのが良いです。

例えば、実装中に「このクラスめっちゃ汚くなってきた」と思えば、
```py
# このクラスめっちゃ汚くなってきた
```
と書いてしまえばよいのです。
ただ、これだと他人が読んだときに「？」となってしまうので、少し整形します。
```py
# TODO: Animalクラスが複雑になってきたので、サブクラスを作って整理する
```
このように、自分が考えていることもコメントに残すことで、
他人が理解しやすいコードになり、リファクタリングもしやすくなります。

### 今後意識したいこと
今まで、
「コメントは処理内容を書くもの」
「考えていることを書いたコメントは要らない」
と考えていましたが、この本を読んでその認識が変わりました。

実際には、
軽く読んだだけでは理解しづらいコードにコメントを書き、
考えたことが他人に役立ちそうな場合は積極的にコメントを書く

ことが重要だと知りました。

これからは、コメントを書くことを恐れず、
**積極的にコメントを書いていきたい**なと思うのと同時に、

コメントを読むときも時間を消費しているわけなので、
**コンパクトに情報を詰め込んだコメントを書く**ことを心がけたいです。

## 理解しやすいコードは短い
### 結論
この実装は必要なのかな、と**悩んだら、その実装は不要**なことが多いです。
可読性を意識しすぎて、分割しすぎたコードは冗長です。

### 詳細
前編後編を通してこの記事を読んできて、

分かりやすく命名すること、
分かりやすくコメントすること、

が大事なのだということは理解できたと思います。
ただ、やり過ぎも良くありません。

例えば、以下のようなコードは、理解しやすいコードでしょうか。
```py:example.py
def mult(x, y):
  answer = x * y
  return answer
```

確かに、answerに答えを代入してそれを返しているので、理解はできます。
ただ、以下のコードのほうがコンパクトでわかりやすいのではないでしょうか。

```py:example2.py
def mult(x, y):
  return x * y
```
このように、直感的にわかるものや、関数内で一度しか使われないようなものには
無理に変数名を付ける必要はありません。

今回は細かなコードについての例を上げましたが、
関数やメソッド、クラス、そもそもの機能などでも同じです。

コードは増えれば増えるほど保守運用が難しくなります。

本当にこのコードは必要なのか？と批判的に考えて、
無駄なものは削ることも、理解しやすいコードを作る上では重要です。

### 今後意識したいこと
私はアプリを作成するときに、
いろんな機能をはじめから実装しようとしてしまうので、
この記事を読んでギクッとしました。笑

また、何でもかんでも変数に入れたほうが安心してしまい、
上の例に挙げたようなコードを書いてしまっていた気が...（汗）

今後は、本当に必要な機能はなにか？このコードは無駄じゃないか？
ということを考えながら、わかりやすいコードを書いていきたいです。

## 最後に
リーダブルコードを読んで、少しコードのお作法を学べた気がします。

ぶっちゃけ、
いろんな方からこの本を読むと良いよ〜と進められていましたが、

この本を読む前は
「ハウツー本嫌いだしな〜」「どうせ堅苦しく書いてるだけでしょ」
とあまり期待していませんでした（**ごめんなさい**）。

でも実際は、
- 全く堅苦しくない（むしろ笑える翻訳がいくつか）
- ハウツー本でもなく、汎用性が高い

というすごく良い本でした。

この本をおすすめできるのは以下のような方です。
- リーダブルコードを読まず嫌いしている
- コードは自己流で読みやすいように工夫している
- プログラミングを始めて半年以上立っている

この記事をきっかけに、
理解しやすいコードを書くことを意識し始めたり、
リーダブルコードを手にとってみたり、
何かしら行動が変わったらすごく嬉しいです。

参考文献：リーダブルコード（ https://amzn.asia/d/aklZpHj ）