はじめに
どうも、未経験からエンジニア転職し半年が経ちました。
今回も前回に引き続きリーダブルコードを元に実務ではどう役に立ちそうか、逆にこれはやめた方が良さそうなど考えていきたいと思います。今回は適切なインデントとコメントに関してです。
前回の記事
4章 美しさ
４章では見た目の美しい、読みやすいコードにするため、適切な改行やインデントに関して記載されていました。リーダブルコードによると、見た目の美しいコードにするには一貫性を意識する必要があるとのこと。
なのでここは空行1つしかあいてないのここは３つ空いてるみたいな一貫性がないコードを記載してしまうと美しくない、読みにくいコードになってきます。ちなみに２つ半角スペース空けなければいけないとか正規的なものはありません。一貫性があれば問題はありませんしそもそも言語によっても記載方法が変わってくるので統一することはできないかと思います。
しかしインデントは半角スペース２つ空けようねとか、ここで改行しましょうねとかそういった規約を作らないと個々が自己流のインデントや改行になってしまうので、個人開発であれば良いかもしれませんが、企業でのチーム開発において非常に読みにくいコードになってしまうのかなと思います。
うちの会社でもコーディング規約があるのでその一例を紹介できたらなと思います。
コーディング規約一例
自分が当時どうインデントを空けたらいいか迷っていた例を紹介したいと思います。この一例では条件がtrueであればbody_codeを変数に代入していくという例文になっています。
- 制御構造が代入の右辺に来る場合は、右辺でインデントを合わせるか、あるいは右辺開始時点で改行しインデントを1レベル下げること。
# good
result = if condition
body_code
end
# good
result =
if condition
body_code
end
# bad
result = if condition
body_code
end
# bad
result = if condition
body_code
end
4章 まとめ
- とにかく一貫性が大事！
そのためにコーディング規約を設けてそれぞれが一貫性を持ったコードを書く必要がある。
5章 コメントすべきことを知る
５章からはコメントに関して記載されていました。まずコメントの目的とは何でしょうか？リーダブルコードでは次のように記載されていました。
コメントの目的は、書き手の意図を読み手に知らせることである。
そしてそのためのポイントは
- コメントすべきでは「ない」ことを知る。
- コードを書いている時の自分の考えを記録する。
- 読み手の立場になって何が必要になるかを考える。
ここら辺に関して関して深ぼって考えていきたいと思います。
5.1 コメントすべきで「ない」ことを知る
この章では一番大事な気がします。そもそも自社開発企業に入社して半年以上経ちますが実際コードにコメントを残したのは1,2回くらいです笑
なぜこんなにもコメントすることが少ないのか。それはコメントしようと思う内容は大体コードを修正することによって必要なくなるからです。
分かりづらい関数、変数名なら命名を変更すれば良いし、分かりづらいコードならリファクタリングして理解しやすいコードにすれば良いって感じですかね。それができれば苦労はしないよ！って話かもしれませんし今実務で絶賛苦戦中ですが笑
ではどういった場合にコメントすればいいんだよという話になってきそうな感じがしますが、自分の基準としては「えっ、なんでこの値代入するの？」とか「なんでここでこんな処理した？」みたいな一瞬他人がコードを読んでいて「は？」ってなるだろうなーって箇所に対してコメントするようにしています。
あとはリファクタリング後でも理解するのが難しいだろうなーと思うような箇所とか。
実務では仕様がわからないとわけわかめ的なコードも結構あります。そういった場合に、こういった意図で記載したというコメントを残しておくと他人がコードを読んだ場合に理解しやすくなるのかなと思いました。
具体的な例というと難しいしあんまりよくない例えになりそうですが
# 〇〇の仕様上定数を100にする必要がある
INITIAL_VALUE = 100
うーん例を考えるのが難しい。また良い例があれば更新します。ここで逆にコメントする必要がないことはコードからすぐ読み取れる内容です。今回であればただ初期値に100を代入みたいなコードをそのまま翻訳したようなコメントは要らないって感じですね。
5.2 自分の考えを記録する
リーダブルコードでは他にもコメントすべきことが書かれていました。実際にまだ実践していないが確かにこれは良さそうだなと思ったのをピックアップしていきたいと思います。
考え方で良かったのは
「監督のコメンタリー」を入れる
というところです。映画監督がこの作品がどのように作られたみたいな制作秘話を語ってもらうことによってよりその作品の理解が深まるように、コードもどのような意図で記載したか、ここがまだ欠陥しているコード等、記載したコードに対する感想、考えをコメントとして残しておくと役立つとのこと。
本書の例だと
//このデータだとハッシュテーブルよりもバイナリーツリーの方が40%も早かった
//左右の比較よりもハッシュの計算コストの方が高いようだ
//このクラスは汚くなってきている
//サブクラス'ResorceNode'を作って整理したほうがいいかもしれない
このようにコードに対する感想やコードの欠陥をコメントに残しておくと他人がコードを読む際により理解が深まるとのこと。もっとリファクタリングできそうだけど現状工数的に難しい、後でリファクタリングしようと思ってるとかそういったことをコードに残しておくのはありだなと思いました。
5.3 読み手の立場になって考える。
人間関係も相手の立場になって考えるって大事ですよね。コードに対するコメントも相手の立場になって考えることが大事らしいです笑
ここで良さそうだなと思ったのは以下の2点
- 事前に言っておいたほうが良さそうなことをコメントに残す
- 要約コメント
まず事前に言ったほうが良さそうなことにコメントに残すに関して。
実務に置いてコメントしたほうが良さそうかもと思ったのは結構重たいクエリ(SQL文を実行)を投げるコードを記載した場合などです。
結構重たいクエリを投げている箇所をデバックする際に、「全然進まなくね？ちゃんとターミナル動いてるのかな？」とちゃんと実行はできているのに重たいクエリのせいで時間がかかり、画面がフリーズしたのかと勘違いしたときがありました。
こういった時に
#時間がこれくらいかかるクエリ
みたいな感じでコメントがあると、勘違いを防ぐことができます。こういった事前に言っておいたほうが良さそうなことをコメントに残すのは良いかもなと感じました。
次に要約コメントについて。
現状は自分で作成したメソッドや関数などを要約するコメントをコードには残しておりません。
代わりにGitHubにプルリクを出した際、詳細にこのメソッドはどういう意図で作成したかなどをGitHub上に記載するようにしています。
5章 まとめ
- コメントするべきじゃないことを知る
コメントしたほうが良いのは
- 事前に言っておいたほうが良さそうなこと
- 要約コメント
- 今後こうしたいなどの改善コメント
6章 コメントは正確で簡潔に
この章はもうタイトルの通りコメントは正確に簡潔に書きましょうねということを言っているだけという感じですかね。コメントも命名と同じくしっかりと考えてコメントするべきだと書かれています。
自分の場合もコメントした後にこれで誤解が生まれないかなとか言い回しは問題ないだろうかなど考え先輩にレビューをお願いしています。それでも大体修正されちゃうんですけどね笑 やっぱ先輩ってすごい。
一点だけ改めて意識しようと思ったのはあいまいな代名詞を避けるということでした。
//データをキャッシュに入れる。ただし、先にそのサイズをチェックする。
//データをキャッシュに入れる。ただし、先にデータのサイズをチェックする。
本書の例のように「あれ」「それ」「これ」のような代名詞があると文章全体の理解に時間がかかるので避けるように心がけたほうがいいと記載されていました。ここはコメントする際改めて意識して行きたいと思います。
6章 まとめ
- コメントはとにかく正確で簡潔に！ 情報密度高い文章にする。
- コメントで代名詞は避ける。
あとがき
いかがでしたでしょうか？今回はリーダブルコード4~6章を要約していきました。コーディング規約に沿って記載するのもついつい忘れてしまい指摘をいただいている毎日です笑
今後7章(いよいよちゃんとコードを例に書いていく)以降も要約していきたいと思いますのでまたご覧いただけますと幸いです。