読めないコードを書かせないために、頼み方を変えた
短く書かれると読めません。自分が読める範囲で書いてもらう話です。

この記事の結論
- 短く書かれると、読めなくなる
- 読めないコードは、自分で直せない
- 多少長くても、分かる書き方を頼む
- 短く書かれると、読めなくなる
- 読めないコードは、自分で直せない
- 多少長くても、分かる書き方を頼む
返ってきたコードが短くまとまっていて、何をしているか分からなかった。読める形で頼むようにしてから、保守できるようになった。
読めない書き方
短く書かれると、こうなる。
- 複数の処理が1行に詰まっている
- 省略記法が使われている
- 変数名が1文字
3つ目が特に厳しい。何を入れている変数か、追わないと分からない。
頼むときに添える
こう書くようにした。
次の条件で書いてください。
- 1行に1つの処理
- 変数名は、中身が分かる名前にする
- 省略記法を使わない
- 各処理にコメントを付ける
短さより、読みやすさを優先してください。最後の1行が要点だ。短く書くのが良いとされているので、明示しないと短くなる。
読めることの価値
読めると、何ができるようになるか。
- 壊れたとき、どこが悪いか見当がつく
- 少し変えたいとき、自分で直せる
- 提案が適切か判断できる
2つ目が日常的に効く。文字を1つ変えるために、毎回頼むのは効率が悪い。
コメントの書き方
コメントにも、求める形がある。
- 何をしているかではなく、なぜそうするか
- 処理の内容は、コードを読めば分かる
- 意図は、書かないと分からない
3つ目が重要だ。半年後に読むとき、必要なのは意図のほう。
長くなることを許容する
読める書き方にすると、行数は増える。
- 5行が15行になることもある
- 動作は変わらない
- 読める分、保守できる
3つ目が目的だ。短いが読めないコードは、他人のコードと同じ。
自分の水準を伝える
どの程度読めるかを、先に伝えている。
- 基本的な文法は分かる
- 高度な書き方は読めない
- 読めない書き方は避けてほしい
3つ目を書くと、説明が必要な書き方が減る。
そのまま使える形
短く賢いコードは、後から読めない。先に制約として書く。
次の条件で書いてください。短さより、読みやすさを優先します。 ・1つの関数は20行以内 ・三項演算子の入れ子を使わない ・省略形の書き方より、行数が増えても分かる書き方を選ぶ ・変数名は略さない($u ではなく $user_id) ・なぜそうしたか説明が要る箇所だけ、コメントを1行 書いた後、「ここは説明が無いと読めない」と思う箇所を自分で挙げてください。
最後の1行が効く。挙がってきた箇所は、たいてい本当に読めない。
読めないものが返ったとき
どうしても読めない場合は、聞いている。
- 「この部分を、読みやすく書き直して」
- 「各行の説明を付けて」
- 「もっと単純な書き方は無いか」
3つ目で、簡単な方法が出てくることがある。最初から最適な方法が返るとは限らない。
後から読み直す
書いた直後ではなく、時間を置いて読み返している。
- 1週間後に読んで、理解できるか確認する
- 理解できないなら、コメントを足す
- 書いた直後は、記憶で読めてしまう
3つ目が盲点だった。書いた直後は意図を覚えているので、説明が足りなくても読める。時間を置くと、本当に読めるかが分かる。この確認を入れてから、半年後に困ることが減った。
既存のコードと揃える
サイトに既にあるコードとも、揃えている。
- 既存の書き方を貼って、合わせてもらう
- 書き方が揃っていると、読みやすい
- 後から見たときに、違和感がない
2つ目が効く。部分ごとに書き方が違うと、読むたびに切り替えが要る。
処理を分ける
長い処理は、分けてもらうようにした。
- 1つの処理が、1つのことだけをする
- 名前を見れば、何をするか分かる
- 分かれていると、一部だけ直せる
3つ目が保守で効く。まとまった長い処理は、少し変えたいだけでも全体を読む必要がある。分かれていれば、該当する部分だけ見れば済む。頼むときに「処理を分けて、それぞれに名前を付けて」と添えている。
読めない書き方の例
避けてほしい書き方を、具体的に伝えている。
- 条件を1行に詰め込む書き方
- 複数の処理を連結する書き方
- 意味が分かりにくい記号の組み合わせ
名前が分からなくても、「こういう形は避けて」と例を見せれば伝わる。以前返ってきた読めないコードを保存しておき、それを示すこともある。言葉で説明するより確実だった。
読む練習になる
読める形で受け取ると、学習にもなった。
- 目に入るだけで、少しずつ覚える
- コメントがあるので、意味が分かる
- 読める範囲が、少しずつ広がる
3つ目が長期的な効果だ。読めない形で受け取っていると、いつまでも読めない。
あわせて読む
- 他人が書いたコードを読むとき、AIに説明させながら進める — 引き継いだサイトのコードが読めませんでした。全体から降りていく順番の話です。
- 色やサイズを変数にしたら、後から変えるのが楽になった — 同じ値を何か所にも書いていました。まとめた後の違いを書きます。
- コメントに何を書くかで、後から読むときの楽さが変わる — 処理の内容を書いても役に立ちませんでした。書くべきことを整理します。
まとめ
- 明示しないと、短くまとめられる
- 「短さより読みやすさを優先」と添える
- コメントには、何をしているかではなく、なぜそうするかを書かせる
- 読める書き方にすると行数は増えるが、保守できる
- 読める形で受け取ると、学習にもなる
新しい記事が出たら、ブラウザの通知でお知らせします。
メールアドレスの登録は要りません。いつでも止められます。
関連記事
RELATED
圧縮できるのは、冗長度があるから。情報の量の測り方を図にした
情報の量は意味では測りません。どれだけ絞り込めたかで測ります。1948年の論文が置いた定義と、英語の冗長度が約50%とい…
HOKKAIDO AI LAB を英語でも読めるようにしました。ボタン1つで翻訳、英語のページを作らなかった理由も
海外から読んでくださる方のために、ヘッダーに英語の翻訳ボタンを付けました。押すと、いま見ているページがその場で英語になり…
相席か個室か。1つの仕組みを何社で使うかを図にした
共有するか分けるかは0か1ではありません。層ごとに決められます。4つの構成と、それぞれで何を引き受けることになるのかを整…