1. はじめに
こんにちは。
Portalkey の しゃり です。
独学で未経験転職し、1年が経ちました。
皆さんご存じ「リーダブルコード」、初学者必読と名高いですよね。
転職時に開いた時と比べ、共感できることや学べるものが増えていたので以下を軸にまとめてみました。
- 自分のためのindex作り「何が書いてある本だっけ…」の備忘録
- 勉強になった点や共感した点の転職時の自分へのコメント
「プロとして駆け出してみたら共感できたよ」「実際に指摘されたよ」「自分もそう思うようになったよ」
2. リーダブルコード
第1章 理解しやすいコード
🔥 実務体験：ぱっと見で分かるように
特に入社直後にレビューで「ぱっと見で分からない」と言われ続けた。
ぱっと見で意図が伝わるように書けるのがベスト。
第１部表面上の改善
第2章 名前に情報を詰め込む
💭 実務体験：命名への指摘
取得した画像のリサイズの関数で、長方形の画像の辺という意味でsideと命名したらsizeの誤字ですか？と指摘され、長さを強調する(byteではないこと)ためにlongに変えたら余計分からなくなったと指摘された。
「プログラミングでよく使われる単語」であることも大事らしい。
pxやrectSizeの方がよいと言われた。そもそもheight, widthで良かった様子。
ループイテレータについては個人的にはコロンブスの卵感があった。
// ❌入れ子になってても気づけない
if (clubs[i].members[j] == users[k]
// ⭕変数とindexの頭文字が違うので間違いに気づける
if (clubs[ci].members[ui] == users[mi]
「名前で迷ったら設計が悪い」は指摘内容や普段のアドバイスで一番言われた言葉かもしれない。
命名に迷ったらoptionオブジェクトでまとめたり、別の関数にするなど設計を変えるとすっきりすることがある。
また、弊社では「命名は意味の塊で4つまで」という指標がある。
文字数や単語数ではない。
createdWorkspaceMemberPostIdはcreated_WorkspaceMemberPost_Idで3つなのでセーフ。
ポートフォリオでがっつりプロダクト固有の略称を使っているので耳が痛い。
第3章 誤解されない名前
🎯 実務体験：命名への指摘２
直近では、UPDATE_LIMITという変数の命名で指摘を受けた。
この命名は、updateはmergeより動作が不正確(不明瞭)で、limitは閾値を含むのかどうかが分からず、単位が不明だった。
結果、MESSAGE_MERGE_THRESHOLDとすることで「秒単位だよ。それより小さければfooをmergeしてね！」という意図が変数名(とコメント)から分かるようになった。
// 時間をmsで扱うことは良くあることなので命名ではなくコメントでゴマかした
const MESSAGE_MERGE_THRESHOLD = 1000 * 10 // 10 seconds
if (message.timestampMs <= MESSAGE_MERGE_THRESHOLD){
本章を読んで、元の命名ではminなのかmsなのかという勘違いも起こるし、スコープが広ければbyteやstring_countの勘違いもあり得るのだと気付いた。
別件だが、ブール変数の接頭辞については、有名な言語やライブラリでも接頭辞が無いのはよく目にするので注意。
HTMLでもautoPlay、open、disabledがあげられる。
disabledは明確に形容詞なので初見でも分かるけど。
第4章 美しさ
💡 実務体験
入社後、「変数宣言は使う順で並べる」「引数は重要順に並べる」はよく言われた。
第5章 コメントすべきことを知る
🔥 実務体験：TODOコメントは消すタイミングを伝える
TODOコメントについては「何があれば消すコメントなのか」を明確にしろという指摘を受けることがある。
// TODO: ○○の部分を○○に書き直したら消す
// 実行時間はo(n2)なので、サイズに気をつける
先輩方は確かにそう書いてた。言語化されたことで実践しやすくなった。
感想
前章でコメント書き過ぎ。多くないか？と思ってたら、この章の1が「コメントするべきではないこと」になっていて構成上手。
第6章 コメントは正確で簡潔に
💭 転職活動体験
未経験時にスカウトをいただいた中で「しゃりさんの記事は日本語がしっかりしていた。これは貴重なことだ」と評価をいただいたことがあった。当時は良く分からなかったこの章で少し分かったかもしれない。
「あいまいな代名詞を避ける」に悪例が載っていた。
データをキャッシュに入れる。ただし、先にそのサイズをチェックする。
確かに、転職時に書いた記事にはそんな書き方はしてなかったかもしれない。「その」を使わないか、使っていても文の主役を明確にしていたはず。
上述でも取り上げた「名前で困ったら設計が悪い」だが、「コメントで困ったら名前が悪い」もあるかもしれないと思った章だった。
第2部 ループとロジックの単純化
第7章 制御フローを読みやすくする
🤔 実務体験と悩み
早期リターンの良さは分かるんだけど、失敗とは言えない場合に早期リターンの正解が分からなくてずっと苦戦してる。
ネストについては未経験時から何かで知っていた。
ただ、自分は浅くしようとし過ぎていて「ネストは悪じゃない」と教わったところだ。
ルールを意識しすぎると「読みやすさ」のための手段なことを忘れがちという戒め。
この本で悪例として書かれていた三項演算子のネストだが、恐らく先輩方(10年以上の戦士)は普通に読める。
今の自分には読みにくいが慣れれば読めるのだろうか？と思うことは三項演算子に限らず多い。入社時に比べれば難なく読めるようになったものも多いが、まだ沢山あるのでこの溝を早く埋めたい。
第8章 巨大な式を分割する
⚠️ 実務体験：不要な変数宣言
入社直後はやりすぎていて、「逆に脳のリソースを取られる」と指摘された。
「読めばわかること」は変数にしないこと。
初心者のレベルで「飲み込みやすい」にすると、上級者にとっては冗長過ぎて読むスピードが落ちる、ぱっと見で把握できる情報量が減るになることをその時に知った。
今の自分は当時の指摘と同じように感じるようになった。
ド・モルガンの法則についても言われたことある。否定を減らす、なるべく||(論理演算子)にする。
当時は無理に全部こなそうとして訳が分からなくなった記憶がある。やることにも使い分けにもその内慣れる。
ただ、今でも複雑なロジックの改善が苦手で時間をかけ過ぎがちだし、ラバーダッキングとDRYの見極めが苦手。
コツがあるなら知りたい。
第9章 変数と読みやすさ
💡 実務体験：将来の追加実装や運用を考える
実務で気づいたのは、最初は変数は少なかったのに手直ししてくうちに入り込んで来たりすること。その流れでセルフレビューしても気付かないことも多い。
実務でもJS(TS/React)ではvarはなるべく使わないようにしてる。多くの場合は設計で避けられるし、避けた設計の方が良いコードになることが多い。転職直後はびっくりした。
第3部 コードの再構成
第10章 無関係の下位問題を抽出する
🔄 実務体験：過剰な切り出し
この章は「関心の分離」の話だと理解した。
これほど整理して説明されたかは定かではないが、実務でも都度1つ1つ何回も教わっている。
「小さな関数の作りすぎ」は入社直後に頻繁に指摘された。全くプログラミングに慣れていない当時の自分にはそれが読みやすかった。
今となっては指摘する側の気持ちが分かる。しかも、当時は「興味を持たなくて良いコード」かどうかは無関係に分割していた気がする。
第11章 一度に1つのことを
📝 実務体験：コーディング外にも活かす
レビューでは言われる頻度が減ったが、質問や説明の会話でよく指摘される。
「１つの質問で１つの答えを求めましょう。それを繰り返し積み重ねましょう。」
第12章 コードに思いを込める
🗣️ 実務体験：日本語分解の重要性
「実装したい処理をまずは主語述語を1つずつの日本語に分解しなさい」
これは先輩から言われ続けた話
第13章 短いコードを書く
🤔 過去の反省
YAGNIの話だと理解した。
未経験のポートフォリオ作成時にも概念としては知ってたが実行に移せなかった。今思うとやはりほとんどのケースで消すべきだったと思う。
第4部 選抜テーマ
第14章 テストと読みやすさ
⚡ 実務体験：開発速度を重視する
「テストは開発速度を上げるためのものなので、開発速度が下がるなら本末転倒」のようなアドバイス受けたことがある。
開発速度=その時の実装、デバッグ、将来にやる機能の追加、削除、改修、...
(完成形を模索しながら開発している0→1のフェーズなので余計にそうなのだと思う)
第15章 「分/時間カウンタ」を設計・実装する
🤖 実務体験
先輩から度々言われる。「機械用に書くなら超短縮できるけど、人間用に書くんだ。」
解説
🔙 振り返り
全章を読んだ後にこの「解説」を読むと刺さることが沢山書いてある。
入社直後の話だが、レビューで「GitHubで差分読むだけだと分からなくて、ローカルで全文確認したんですよ」というようなことを言われたの思い出した。
3. 終わりに
初学者必読なのが良く分かる本でした。
入社直後に比べれば、命名もコードの意図も指導され続けて、やっと指摘される回数が減ったように思っています。
しかし永遠に「こう書けばこういう意図だと伝わるよね」というアドバイスを受けます。
やはり改善点が無限にある様子。
初学者にとって難しいのは、慣れるほど読みやすいコードの枠が広がることだと思います。つまり、慣れる前は上級者に読みやすいコードでも読みにくく、自分が読みやすいと避けた書き方が一般的には読みやすいことが良くあります。その気持ちは忘れないようにしたいです。
また、読書を記事にする行為を初めてやってみました。
労力がかかることを実感し、何か手を打たないと時間が溶けてしまいそうです。
今回は書き出すことで読書の復習にはなったが、内容としては自分が懐かしみを味わうだけになってしまったようにも思う。
次に読書を記事にする際は、どのような形式が良いのか悩む。
Discussion