この記事は、リーダブルコードから学んだこと【前編】の続きです。
前編、後編のどちらを読んでも理解できる内容になっていますが、
興味があればぜひ前編も読んでいただけると嬉しいです。
はじめに
こんにちは。エンジニアを目指す大学３年生です。
この記事では、プログラミング歴2年ちょっとの新人（私）が、
リーダブルコードを読んで気づいたことや学んだことを書き留めています。
あらためて、リーダブルコードは、真面目すぎず面白く、
「良いコードとはなにか」について分かりやすく述べた本だと思います。
一つの記事にまとめるとボリュームが大きくなりすぎるので、２つの記事に分けました。
この記事は後編です。
前編、後編を通して、以下の4つを扱います。
- 他人は未来の自分
- 誰が見ても処理がわかる命名をする
- コメントは、理解が早くなるように書く
- 理解しやすいコードは短い
今回は後編で、下2つを扱っています。
この記事が、
新しい気づきを得たり、知っていることを復習するきっかけになれば嬉しいです。
前編はこちら⏬
https://qiita.com/natsu0627pooh/items/9184b9b67944a4931ad5
コメントは、理解が早くなるように書く
結論
コメントは、他人がコードを理解するのを助けるためのものです。
多すぎても少なすぎてもわかりにくいコードとなってしまうので、
ちょうどよいコメントを書く必要があります。
詳細
コメントを書くべきコードは、以下のようなものがあります。
- 処理が複雑で、他人がコードを見たときに直感的に理解できないコード
- 他人が疑問を持ちそうなコード
- 他人に考えていることを伝えたい場合
ただし、他人はコメントを読むときも時間を使っているので、
その時間で読めるコード以上の価値があるコメントを書く必要があります。
一方、コメントを書くべきでないコードには、以下のようなものがあります。
- 処理が単純で、誰が見ても直感的に実装内容がわかるコード
- コード自体をシンプルにできる場合
コメントを書くべきでないコードは、ここに書いた内容で大体理解できそうなので、
コメントを書くべきコードについて詳しく述べます。
直感的に理解できないコード
コードを見ただけではすぐに何をしているのか理解できないようなコードには、
コメントをつけることで理解の助けになります。
ただ、ここでいう「すぐに何をしているのか理解できないようなコード」は、
消して汚いコードというわけではなく、洗練されたコードのことを指します。
もし汚いコードなのであれば、まずはきれいなコードに直すことを優先します。
エンジニアは、
優れたコード＞汚いコード＋優れたコメント
というふうに考えているそうです。
疑問を持ちそうなコード
他人が見たときに、疑問を持ちそうなコードにはコメントをつけるのが良いです。
例をあげます。
image_quality = 0.72
例えば、上のようなコードを見て、なにか疑問を持ちませんか？
批判的にコードを見ている人は、
「何をどう考えて0.72にしたのか？もっと低くてはだめなのか？」
などと疑問を持ちそうです。
そこで、以下のようにコメントを付けます。
image_quality = 0.72 # 0.72 ならユーザはファイルサイズと品質の面で妥協できる
すると、読み手に値を決めた背景が伝わり、
数字の妥当性を確かめるなどという無駄な作業が減ります。
このように、他人が疑問を持ちそうなコードには、
その疑問を解消できるようなコメントが書けると良いです。
考えていることを伝えたい場合
実装中、なにか気がかりなことがあったり、
他の人にも知っておいてほしいようなことがある場合にも、
コメントを書くことが望ましいです。
はじめは難しく考えすぎず、思ったことをそのまま書いてしまうのが良いです。
例えば、実装中に「このクラスめっちゃ汚くなってきた」と思えば、
# このクラスめっちゃ汚くなってきた
と書いてしまえばよいのです。
ただ、これだと他人が読んだときに「？」となってしまうので、少し整形します。
# TODO: Animalクラスが複雑になってきたので、サブクラスを作って整理する
このように、自分が考えていることもコメントに残すことで、
他人が理解しやすいコードになり、リファクタリングもしやすくなります。
今後意識したいこと
今まで、
「コメントは処理内容を書くもの」
「考えていることを書いたコメントは要らない」
と考えていましたが、この本を読んでその認識が変わりました。
実際には、
軽く読んだだけでは理解しづらいコードにコメントを書き、
考えたことが他人に役立ちそうな場合は積極的にコメントを書く
ことが重要だと知りました。
これからは、コメントを書くことを恐れず、
積極的にコメントを書いていきたいなと思うのと同時に、
コメントを読むときも時間を消費しているわけなので、
コンパクトに情報を詰め込んだコメントを書くことを心がけたいです。
理解しやすいコードは短い
結論
この実装は必要なのかな、と悩んだら、その実装は不要なことが多いです。
可読性を意識しすぎて、分割しすぎたコードは冗長です。
詳細
前編後編を通してこの記事を読んできて、
分かりやすく命名すること、
分かりやすくコメントすること、
が大事なのだということは理解できたと思います。
ただ、やり過ぎも良くありません。
例えば、以下のようなコードは、理解しやすいコードでしょうか。
def mult(x, y):
answer = x * y
return answer
確かに、answerに答えを代入してそれを返しているので、理解はできます。
ただ、以下のコードのほうがコンパクトでわかりやすいのではないでしょうか。
def mult(x, y):
return x * y
このように、直感的にわかるものや、関数内で一度しか使われないようなものには
無理に変数名を付ける必要はありません。
今回は細かなコードについての例を上げましたが、
関数やメソッド、クラス、そもそもの機能などでも同じです。
コードは増えれば増えるほど保守運用が難しくなります。
本当にこのコードは必要なのか？と批判的に考えて、
無駄なものは削ることも、理解しやすいコードを作る上では重要です。
今後意識したいこと
私はアプリを作成するときに、
いろんな機能をはじめから実装しようとしてしまうので、
この記事を読んでギクッとしました。笑
また、何でもかんでも変数に入れたほうが安心してしまい、
上の例に挙げたようなコードを書いてしまっていた気が...（汗）
今後は、本当に必要な機能はなにか？このコードは無駄じゃないか？
ということを考えながら、わかりやすいコードを書いていきたいです。
最後に
リーダブルコードを読んで、少しコードのお作法を学べた気がします。
ぶっちゃけ、
いろんな方からこの本を読むと良いよ〜と進められていましたが、
この本を読む前は
「ハウツー本嫌いだしな〜」「どうせ堅苦しく書いてるだけでしょ」
とあまり期待していませんでした（ごめんなさい）。
でも実際は、
- 全く堅苦しくない（むしろ笑える翻訳がいくつか）
- ハウツー本でもなく、汎用性が高い
というすごく良い本でした。
この本をおすすめできるのは以下のような方です。
- リーダブルコードを読まず嫌いしている
- コードは自己流で読みやすいように工夫している
- プログラミングを始めて半年以上立っている
この記事をきっかけに、
理解しやすいコードを書くことを意識し始めたり、
リーダブルコードを手にとってみたり、
何かしら行動が変わったらすごく嬉しいです。
参考文献：リーダブルコード（ https://amzn.asia/d/aklZpHj ）