こんにちは。
本日からサッカー解禁！やりますよ！
この時をどれだけ待ちわびたか。。
はじめに
ここ最近プルリクを出した時に、良かれと思って書いたコメントについて先輩からご指摘をいただきました。
書いたコメントはこんな感じ。
# 〇〇の計算
レビュー内容はと言うと、コメントには「なぜそのようなコードにしたのか？」や「そのコードの問題点（要改善点）」などを書くようにしましょう。と。。
やってまいました。。勉強不足です。
そんな背景があり、かの有名な「リーダブルコード」を読んでみました。
今回はそのアウトプットを書いていこうと思います。
結構学びがありましたので、ぜひご参考にしていただければと思います。
では、早速行きましょう。
本日の概要 : リーダブルコード第1部のまとめ
- こんな方におすすめ
- 第1部 表面上の改善
- 理解しやすいコード
- 名前に情報を詰め込む
- 誤解されない名前
- 美しさ
- コメントすべきことを知る
- コメントは正確で簡潔に
- 総括
こんな方におすすめ
- エンジニアになって数ヶ月が経った方
- 優れたコードってどんなコードなんだろ？と思っている方
- 僕みたいにコメントなどにご指摘をいただた方
- 良いコード、読みやすいコードを書くためのテクニックを知りたい方
などなど
第1部 表面上の改善
理解しやすいコード
鍵となる考え
- コードは理解しやすくなければいけない
- コードは他の人が最短時間で理解できるように書かなければいけない
名前に情報を詰め込む
鍵となる考え
- 名前に情報を詰め込む（名前を見ただけで情報を読み取れるようにすること）
- 気取った言い回しよりも明確で正確なほうがいい
- 抽象的な名前よりも具体的な名前を使う
まとめ
- 明確な単語を選ぶ
- 汎用的な名前は避ける
- 具体的な名前を使って、物事を追加する
- 変数名に大切な情報を追加する
- スコープの大きな変数には長い名前をつける
- 大文字やアンダースコアなどに意味を含める
誤解されない名前
鍵となる考え
- 名前が「他の意味と間違えられることはないか？」何度も自問自答する
まとめ
- 最善の名前とは、誤解されない名前である
- 自分が書いたコードを読んでいる人が、自分の意図を正しく理解できること
- ex)
- 上限の限界値を決める時：max_ / min_ を前につける
- 包含的範囲であれば：first / lastを使う
- ブール値に名前をつける時：is / has などを使う
美しさ
鍵となる考え
- 一貫性のあるスタイルは「正しい」スタイルよりも大切だ
- 優れたソースコードは目に優しいものでなければならない（使いやすい）
まとめ
- 一貫性と意味のあるやり方でコーディングを整形すれば、素早く簡単にコードを読むことができる
- 読み手が慣れているパターンと一貫性のあるレイアウトを使う
- 複数のコードブロックで同じようなことをしていたら、シルエットも同じようなものにする
- コードの「列」を整列すれば、概要が把握しやすくなる
- 似ているコードは似ているように見せる
- ある場所でA B Cのように並んでいたものを他の場所でB C Aのように並べてはいけない。意味のある順番を選んで、常にその順番を守る
- 関連するコードをまとめてブロックにする
- 空行を使って大きなブロックを論理的な「段落」に分ける
コメントすべきことを知る
鍵となる考え
- コメントの目的は、書き手の意図を読み手に知らせることである
- コードからすぐにわかることをコメントに書かない→今回レビューで指摘された箇所です
まとめ
- コメントには、それだけの価値を持たせる
- コメントすべきで「ない」こと
- コードからすぐに抽出できること
- ひどいコードを補う「補助的なコメント」。コメントを書くのではなくコードを修正する
- 記録すべきこと
- 自分の考えを記録する
- なぜコードが他のやり方ではなくこうなっているのか
- コードの欠 をTODO: や XXX: などの記法を使って示す
- 定数の値にまつわる「背景」を書く
- 読み手の立場になって考えること
- コードを読んだ人が「疑問」に思うところを予測してコメントをつける
- 平均的な読み手が驚くような動作は文書化しておく
- ファイルやクラスには「全体像」のコメントを書く
- 読み手が細部に捕われないように、コードブロックにコメントをつけて概要をまとめる
コメントは正確で簡潔に
鍵となる考え
- コメントは領域に対する情報の比率が高く慣れればいけない
まとめ
- コメントを書くのであれば、できるだけ明確で詳細に正確に書くべき。また、簡潔なものでなければならない
- 複数のものを指す可能性がある「それ」「これ」などの代名詞をさける
- 関数の動作はできるだけ正確に説明する
- コメントに含める出力の実例を慎重に選ぶ
- コードの意図は、詳細レベルではなく、高レベルで記述する
- よくわからない引数にはインラインコメントを使う
- 多くの意味が詰め込まれた言葉や表現を使って、コメントを簡潔に保つ
総括
今回は、リーダブルコードの第1部についてまとめてみました。
エンジニアになり、だいぶコードの読み書きができるようになってきましたが、正直コードの意味や意図をあまり考えられていなかった。
今回のコードレビューからまた一つ学び、リーダブルコードを通じて学んことを実績して行きたいと思います。
まずは指摘箇所でもあった「コメントすべきことを知る」を早速週明けから実践です。
まだまだ学ぶことがたくさんあります。頑張ります！！
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
次は、リーダブルコードの第2部をまとめていきます。
以上、ハチマキでした。
