読めないコードを書かせないために、頼み方を変えた

• 短く書かれると、読めなくなる
• 読めないコードは、自分で直せない
• 多少長くても、分かる書き方を頼む

返ってきたコードが短くまとまっていて、何をしているか分からなかった。読める形で頼むようにしてから、保守できるようになった。

読めない書き方

短く書かれると、こうなる。

• 複数の処理が1行に詰まっている
• 省略記法が使われている
• 変数名が1文字

3つ目が特に厳しい。何を入れている変数か、追わないと分からない。

頼むときに添える

こう書くようにした。

次の条件で書いてください。

- 1行に1つの処理
- 変数名は、中身が分かる名前にする
- 省略記法を使わない
- 各処理にコメントを付ける

短さより、読みやすさを優先してください。

最後の1行が要点だ。短く書くのが良いとされているので、明示しないと短くなる。

読めることの価値

読めると、何ができるようになるか。

• 壊れたとき、どこが悪いか見当がつく
• 少し変えたいとき、自分で直せる
• 提案が適切か判断できる

2つ目が日常的に効く。文字を1つ変えるために、毎回頼むのは効率が悪い。

コメントの書き方

コメントにも、求める形がある。

• 何をしているかではなく、なぜそうするか
• 処理の内容は、コードを読めば分かる
• 意図は、書かないと分からない

3つ目が重要だ。半年後に読むとき、必要なのは意図のほう。

長くなることを許容する

読める書き方にすると、行数は増える。

• 5行が15行になることもある
• 動作は変わらない
• 読める分、保守できる

3つ目が目的だ。短いが読めないコードは、他人のコードと同じ。

自分の水準を伝える

どの程度読めるかを、先に伝えている。

• 基本的な文法は分かる
• 高度な書き方は読めない
• 読めない書き方は避けてほしい

3つ目を書くと、説明が必要な書き方が減る。

読めないものが返ったとき

どうしても読めない場合は、聞いている。

• 「この部分を、読みやすく書き直して」
• 「各行の説明を付けて」
• 「もっと単純な書き方は無いか」

3つ目で、簡単な方法が出てくることがある。最初から最適な方法が返るとは限らない。

後から読み直す

書いた直後ではなく、時間を置いて読み返している。

• 1週間後に読んで、理解できるか確認する
• 理解できないなら、コメントを足す
• 書いた直後は、記憶で読めてしまう

3つ目が盲点だった。書いた直後は意図を覚えているので、説明が足りなくても読める。時間を置くと、本当に読めるかが分かる。この確認を入れてから、半年後に困ることが減った。

既存のコードと揃える

サイトに既にあるコードとも、揃えている。

• 既存の書き方を貼って、合わせてもらう
• 書き方が揃っていると、読みやすい
• 後から見たときに、違和感がない

2つ目が効く。部分ごとに書き方が違うと、読むたびに切り替えが要る。

処理を分ける

長い処理は、分けてもらうようにした。

• 1つの処理が、1つのことだけをする
• 名前を見れば、何をするか分かる
• 分かれていると、一部だけ直せる

3つ目が保守で効く。まとまった長い処理は、少し変えたいだけでも全体を読む必要がある。分かれていれば、該当する部分だけ見れば済む。頼むときに「処理を分けて、それぞれに名前を付けて」と添えている。

読めない書き方の例

避けてほしい書き方を、具体的に伝えている。

• 条件を1行に詰め込む書き方
• 複数の処理を連結する書き方
• 意味が分かりにくい記号の組み合わせ

名前が分からなくても、「こういう形は避けて」と例を見せれば伝わる。以前返ってきた読めないコードを保存しておき、それを示すこともある。言葉で説明するより確実だった。

読む練習になる

読める形で受け取ると、学習にもなった。

• 目に入るだけで、少しずつ覚える
• コメントがあるので、意味が分かる
• 読める範囲が、少しずつ広がる

3つ目が長期的な効果だ。読めない形で受け取っていると、いつまでも読めない。

まとめ

• 明示しないと、短くまとめられる
• 「短さより読みやすさを優先」と添える
• コメントには、何をしているかではなく、なぜそうするかを書かせる
• 読める書き方にすると行数は増えるが、保守できる
• 読める形で受け取ると、学習にもなる