久しぶりに記事書いてみます。
最近、会社で「輪読会」を始めました。
なぜ輪読会を始めたかというと、「技術に対して議論する場を増やしたい」という声が社内から上がったことが起因しています。
社内のコミュニケーションが多いとは言えない中で、何かきっかけを作りたい、と思ったのも理由の一つです。同じ技術書を読んでいく中で、少しでも学びを得て、エンジニアとしての成長を実感してもらいたいというのもあります。
記念すべき最初の本は・・・
輪読会、記念すべき最初の本は名著「リーダブルコード」を選びました。
リーダブルコード
コードは理解しやすくなければならない。本書はこの原則を日々のコーディングの様々な場面に当てはめる方法を紹介する。
名前の付け方、コメントの書き方など表明上の改善について。
コードを動かすための制御フロー、理論式、変数などループとロジックについて。
またコードを再構成するための方法。さらにテストの書き方などついて、楽しいイラストとともに説明する。(「リーダブルコード」引用)
輪読会の進め方
毎週1回、午前中の15~30分程時間を取り、それぞれ読んできた内容について考えたこと・疑問に思ったことを出し合います。誰か発表する人を用意する等、特に形式は決めずに進めました。
普段はチームが異なる人と話せる場としても機能しているかな、という実感があります。
輪読会参加前のメモ書きをまとめます
輪読会に参加するにあたり、毎回章ごとに考えたこと・感じたことをメモしていました。輪読会の忘備録として、今後数回にわたり各章のメモ書きをまとめていきます。
第1章:理解しやすいコード
1.2 読みやすさの基本定理
鍵となる考え方:コードは他の人が最短時間で理解できるように書かなければいけない
(「リーダブルコード」p.3より)
- 「最短時間」というのはあまり意識してなかったかもしれない。
- コメントはかなり書くようにしているし、関数(メソッド)には引数、戻り値の論理名・物理名・型を明記している。
- が、「過不足ないか?コメントを書きすぎて、逆に見づらくなっていないか?」等、もっと意識するといいのかも。
1.3 小さいことは絶対にいいこと?
1.4 「理解するまでにかかる時間」は競合する?
(「リーダブルコード」p.4より)
- 短く書ければいいけど、短くしたことで逆に見づらくなるのは本末転倒
- 「読みやすい」コードで、かつより短くかければベスト。常に「このコードは理解しやすいだろうか?」と自問自答する。
第2章:名前に情報を読み込む
2.1 明確な単語を選ぶ
2.2 tmpやretvalなどの汎用的な名前を避ける
(「リーダブルコード」p.10~15より)
-
「~を取得する」処理の関数名を考えたときに、安易に「get~」としてしまいがちだが、一歩立ち止まってもっと適切な名前がないか考える
- 「オブジェクトから値を取得する」:これだったら、**getVal()**がよいだろう
- 「DBからデータを検索して必ず検索対象の1件を取得する」:getはDB取得等、別のところから情報を取得するときは適さない。この場合はfindを使おう
- 「DBからデータを検索してN件取得する」:fetch~
-
個人的に「tmp」は一時的な情報を格納するオブジェクトを定義するときによく使う。スコープをまたいで使ったりする場合は「tmp」は使わない!
-
スコープを意識する:その変数は関数内のみだけで使うのか、メンバ変数やグローバル変数として使うのか?スコープの範囲が限定されていれば、「tmp」等の汎用的な名前をつけてもよい。(と思う)
// APIからデータを取得(一時格納オブジェクトに格納)
const tmpResData: any = res?.data.payload.data;
- ループイテレータに以前は特に意識せず「i,j」とか使ってたが、「i」や「j」だけだと、バグに気づきにくい・意味合いも不適切、なのでもう書かないようにする。
2.4 名前に情報を追加する(「リーダブルコード」p.19~22より)
- 「値の単位」については、ある程度「型」(int, float, double)で担保できる、と考えて「_ms」(ミリ秒)まで変数名にはこだわってないが…どこまでやっているだろう?
- 時間などの場合はミリ秒なのか、秒なのか等、細部まで意識する必要があるので扱う値の範囲を表現できる変数名のほうがよさそう。
const textCount : number = 40; // 整数(マイナスを含む)想定かなぁ・・・これだけだとわからない!
2.6 名前のフォーマットで情報を伝える(「リーダブルコード」p.25~26より)
- 各プロジェクトにコーティング規約があれば、それに準拠する。(フォーマットも有効活用)
- Javaであれば:Google Java Style Guideを準拠しているプロジェクトは多いはず
- クラス・インターフェース名 = UpperCamel(UserImpl)
- メソッド名 = lowerCamel(findUserInfo)
- 定数ではない変数(フィールド)名:lowerCamel(String userName)
- 定数:CONSTANT_CASE
- HTMLタグのId, class指定はできてないプロジェクトもあるので統一したい
<!-- 例:idの区切り文字にはアンダースコア, classの区切り文字はハイフン -->
<div id="middle_colomn" class="main-content">
第3章:誤解されない名前
名前が「他の意味と間違えられることはないだろうか?」と何度も自問自答する。(「リーダブルコード」p.30より)
3.1 例:filter()(「リーダブルコード」p.30より)
- filterという関数名自体はJavaScriptの高階関数(関数を引数、戻り値として扱う関数)で使われていたりするのでさほど違和感なかった。
3.2 例:Clip(text, length)(「リーダブルコード」p.30~31より)
- 最大文字数を表現する際、安易に「max_length」と使ってしまったことがあったが、文字数であれば「max_chars」としたほうが適切だったなぁと自戒
- (バイト数のcountではないよ、と明確にするのがいいかも)
- 最大バイト数等も考慮するケースにおいては、明確に「最大バイト数」(max_bytes)「最大文字数」(max_chars)としたほうが良い気がする。
3.3 限界値を含めるときはminとmaxを使う
3.4 範囲を指定するときはfirstとlastを使う(「リーダブルコード」p.31~32より)
- 最大、最小を表す際はmin,maxをつけることは意識していたが、範囲指定のときにfirst,lastを使うのは明示的で非常にわかりやすいと感じる。
- 日付の範囲指定等には、「from」「to」をよく使う
3.6 ブール値の名前(「リーダブルコード」p.33~34より)
- boolean値は「is~」等はつけているが、デフォルト値を「true」にするか、「false」にするかはいつも悩む・・・
- フラグ値をONにするのか、はじめからONになっているものをOFFにするのか・・・結構混在するかも。
- 「is,has,can,should」をつけるとわかりやすい
- 名前には否定形ではなく、肯定形
【参考】
うまくメソッド名を付けるための参考情報:
https://qiita.com/KeithYokoma/items/2193cf79ba76563e3db6
第1~3章 まとめ
リーダブルコード、普段は本棚に置きっぱなしで・・・今回、輪読会をするにあたり、久しぶりに読んでみると気づきが多くありました。
- 常に他人が読みやすいコードを意識して、見やすさ・わかりやすさを重視する
- コメント等を補足し、コードを理解する時間を早められるように努力する
- 「名前」は重要。名前から得られる情報は多いので、変数名・クラス名・メソッド名etc・・・それぞれの名前づけをより意識する
次の記事では、第3~6章のメモを書いていこうと思います。