📘

リーダブルコードを読んだので語る

に公開
ポエム
idea

文系未経験新卒エンジニア4年目

リーダブルコードを読み終えたのでえらそうに語る。

ちなみに新進気鋭の1年目の時に読もうとしたが、難しくて読むのをやめた。
（「新卒がリーダブルコードを読んだ感想」とか書いてる人はすごいと思う）

本書の気になる内容を取り上げて語る。（意訳含む）

では早速。

コードは理解しやすくなければならない

正しい原則な気がするけど、なんかモヤっとする。
その理由は「誰のために」がないからだと思う。

本書では「他の人」や「想像上の誰か」のためとしていたが、
私はそれだと飲み込めない。

よって、
「プロジェクトに新しく入ってきた人が理解しやすい」
を理解しやすいコードの基準とすることにした。

良い名前は「誤解されない名前」

↓そのために
① 具体的な情報を詰め込む
② スコープが狭い時は短い名前、広いときは長くても正確な名前がよい

普段から命名するときは、以下を基準にしていた（自己流）

  • 内容を正確に表す
  • 追いやすい
  • 上記2つ＋できるだけ短く

とはいえ曖昧な基準だったため、
命名に時間がかかる（悩む）

これがだるい

そんな中で誤解されない名前は良い基準をもらえた。

① 具体的な情報を詰め込む

とりあえず長くてもいいから名前に情報をいれちゃう。
補完機能もあるし、リネーム機能（同じ変数名を一斉に変換するやつ）もあるからとりあえず書いちゃう。

② スコープが狭い時は短い名前、広いときは長くても正確な名前がよい

  • スコープが狭い：説明（定義）がすぐそばにあるから多少誤解されやすくてもOK。
    　　　　　　　　それより機能性。
  • スコープが広い：遥か遠くから参照できるから名前から内容が誤解なく伝わる方がいい。
    　　　　　　　　定義見にいくのだるいし。

という理由づけ。（だった気がする）

短くすることばかり考えていたのでこの基準がもらえたのはでかい。
名前考える時間がだいぶ短くなりそう。

フォーマットが美しいコードは読みやすい

読みやすいというか読む気になる。
フォーマットのショートカット押すだけなのにそれすらしない人をよく見る。
（レガシーでひどい現場しか知らないだけかも）

自分が忘れる可能性もあるということで自戒の取り上げ。

長いコードは空行で段落を分ける

（長く見える時点でまずはリファクタリングを考えろというのは置いておいて）
文章書く時と同じ。

無意識にやっていたような気がするが、認識はしていなかったため取り上げ。

正しさより一貫性

プロジェクトに古来より存在するコードはフォーマットが見づらい場合がある。
ただ、そこに一般的に見やすいフォーマットを一部入れ込んだとしても、
全体で見たら変に見えたり、
最悪誤解を生む場合もある。（「なんでここだけフォーマット違うんだ？」という感じで）

背景 / 理由はコメントしていい

// ○○としたかったが、△△という理由でこのように実装した

思い返すと、
ソースを見ているとき「この人なんでそうした？」と思い、あっちこっち苦労しながら追ってみると
「あぁ、そういう理由ね」となることが何回かあった。
そういう苦労がなくなるのは素敵だ。

「コメントは説明するもの」 と思っていたため、世界が広がった感じがした。

あと、今までだと背景 / 理由が書いてあっても
「はいはい、そういう理由ね」
で終わってたけど、
これからは
「実装の理由が書いてある...　この神の名前は...？（コミット履歴検索）」
と思えるようになったのがとても気分がいい。

定数は背景を示すコメントをつけるとよい

「背景のコメント」については既出だが、定数については特に意識するべき。
理由は定数にはロジックがなく、読んでも分からないから

// 20より大きいと表示崩れが起きる
private static final int MAX_LABEL_LENGTH = 20;

新しい人が最も難しいのは全体像の理解

これはホントにそう。
自分に刻み込むという意味で取り上げ。

毎回新しい案件に入るときに時間がかかるのが「全体像の把握」。

でも毎回退場するころには忘れてる。（なんで？）

本書では「クラスなどの高レベルのソースに全体像の説明をいれるべし」とあったが、
あらゆるドキュメントで意識したい。
（そんなこと言ったら本書の内容はどんなドキュメント作成にも応用できるが）

（反論）名前付き引数コメント

こういう時

connect(10)

こうするのもありって言っていたが、、、

connect(/* timeout_ms = */ 10)

ホントか？



やるならこっちだと思う。

private static final int CONNECTION_TIMEOUT_MS = 10;
connect(CONNECTION_TIMEOUT_MS);



本番稼働しているからデプロイしないけど、
コメントだけ入れてコミットするとかならありか？？

入出力の実例をコメントに書いちゃう

ホントは言葉でロジックを伝えられた方がいいけど、
実例を見せた方が早いって場合がある。
そういう時はマジであり。

/**
 * ユーザー入力を検索用に正規化する。
 * 例:
 * "  ABC-123 " -> "abc123"
 * "ＡＢＣ１２３" -> "abc123"
 */
public String normalizeForSearch(String input) {
    if (input == null) {
        return "";
    }

    String normalized = Normalizer.normalize(input, Normalizer.Form.NFKC);
    return normalized
            .trim()
            .toLowerCase()
            .replace("-", "");
}

ネストは浅いほうがいい

それはそう。
ネストが深いと読む気がなくなる。
でも没頭しているとやりがちなので自戒の取り上げ。
（普通に前科アリ）

三項演算子は読みやすくなる時だけ使う

三項演算子は読みにくいから普通に嫌いなのだが、
「読みにくいのは俺だけかもしれん」ということで使うなと言えなかった。
が、
「リーダブルコードに書いてあったから」と言えるので助かる。

ガード節を使う

（使用はしていたが、）正直、ガード節という語を知らなかった。

「エラーとか、早めにはじきたい時にreturnとかcontinueとか読みやすいね」と思っていた程度で、意識的な使用はしていなかった。

改めて理解すると普通に神。
だって追うときにreturnより下の処理読まなくていいんだもん。

でもelseとの使い分けはしっかりわかっておく必要がある。
以下チャッピーの回答

else とガード節の使い分け

  • ガード節

    • 異常系・前提条件
    • 処理しないケースを早く弾く
    • return / continue

  • else

    • 正常系どうしの分岐
    • どちらも読む必要がある
    • 業務ロジックの分岐

範囲や条件文が複雑になるときはnot条件を考えてみる

本書では　「ド・モルガンの法則を使う」 とあったが、
より記憶に残りやすいようにnot条件で覚えようと思う。

if文で範囲を指定しているとたまにわけわかんなくなる。
そういう時は一旦not条件で考えてみるとスッキリするかもしれない。
（例がない。ごめん。）

すべてにおいてスコープを考える

好きだから取り上げ。

余計なことを考えなくていいように。
忘れていいものは忘れていいように。

設計書もドキュメント、コードもドキュメント

本書で一番勉強になった部分。

最近はAIを使って「設計駆動開発」を行う記事がよく出ていて、
設計書がどれだけ大事かを考える機会が多かった。

その影響からか、
「製品を説明するドキュメントは設計書まで」
と思い込みそうになっていた。

でもまだコードは見ないといけないし、
設計書では表現しきれない（表現していない）ところがコードにはある。

要件定義書からつながる流れにある、詳細設計書をより詳細化した、
いわば 「詳細詳細設計書」 としてコードをとらえようと思った。

問題や設計を言葉に出すと解決しやすくなる

ぬいぐるみに事象を喋っていると自然と解決策が思い浮かぶ話。

自分はどうしているかなと振り返ると、
図をつけて事象をexcelにまとめていた。

事象の記録にもなるし、資料作成の練習にもなるし、説明するときは最悪資料渡せばいいしで、
悪くない方法と思っている。

喋る方が早いし、何より理論立てて喋る練習にもなるから喋る方もやっていきたい。

ライブラリ / 共通クラスを積極的に使う

実装しなくていいしテストもしなくていい。

神。

以前の現場で製造が終わった後に共通クラスがあることを知ったことがあり、
自戒の取り上げ。

この世の中、
私が思いつくようなものは既に誰かがやっているので、
「このロジックどう作るんだ？」と思ったらまずはライブラリを探そう。

コードは書かないほうがいい

これ。

「コード書くぞ！」 とエンジニアになったけど結局はこれなんです。

書かなければ書かないほど読みやすい。

だって読まなくていいんだから。

でも夢中になっていると忘れがちな考えだから、深呼吸して思い出したい。
（思い出せるか？？）

（番外）いいたいこと

コメントの信用度

本書ではコメントに関する記述が割と多かった。
それ自体はとても勉強になったが、コメントが間違っている場合がある。

「コメントが間違っている」とは、コメントの内容と、コードの内容が違うということ。
原因はだいたいコメントの修正漏れ。
コードは修正したけどコメントは修正していない場合。

動かせばコメントと動きが違うからわかるけど、
無駄な時間が発生する。

私が経験したプロジェクトでは少なからずあったので、
コメントを100信用するのは危ない。

Discussion